Ptidej Team

This is an old revision of the document!

Guide to comment in the code of PTIDEJ Project

While contributing to the project, you may encounter issues that you could ask help from colleagues, with that in mind, a tool to create issues automatically in the github PTIDEJ repository was made.

It will read and generate title, tags, descriptions and semantics automatically in the following order:

1 - The first line of comment is always the following

// TODO

2- To continue to create the issue of step 1, keep using // in the next lines without real code of the class

Correct

// TODO 
// same issue comment
someMethod()

Wrong

// TODO 
someMethod()
// same issue comment

3 - Issues are created by files, so different "// TODO" in same file and SEPARATED by at least ONE LINE REAL OF CODE will be in the same issue but different section

One TODO

// TODOx`
// something
// TODO
// something else
method();

Two TODO

// TODO
// something
method();
// TODO
// something else

Three TODO

// TODO
// something of issue 1
method();
// TODO
// something of the issue 2

// TODO
// something of the issue 3
// TODO
// something else of the issue 3

Next steps are optional but highly encouraged to give the issues FAST DESCRIPTION and a precise TITLE

4- To generate extra information to make a precise tittle and description, inside any TODO, you can add certain codes in the middle of the comment to create context to the issue reader

Example 1

@#ADD_METHOD = “Here needs to add this method some_method()”

// TODO
// @#ADD_METHOD some_method()

Result of example 1 in FAST DESCRIPTION

- The method some_method() needs to be added

Result of example 1 in the TITLE

Some_Library on File_Name.java -> 1 Add Method

Result of example 1 TITLE if not used the @#ADD_METHOD

Some_Library on File_Name.java

5- Following are all the ID's for these codes, what they mean and how to use respectively

If the ID code has a @#END_, any text in the middle of the start and the @#END_, will be used in the description

@#ADD_METHOD

"Here needs to add this method"

@#ADD_METHOD something_method()

@#REMOVE_METHOD

"Here needs to remove this method"

@#REMOVE_METHOD something_method()

@#ADD_CONSTANT

"Here needs to add this constant"

@#ADD_CONSTANT SOME_CONSTANT

@#REMOVE_CONSTANT

"Here needs to remove this constant"

@#REMOVE_CONSTANT SOME_CONSTANT

@#FIX_BUG / @#END_BUG

Need to fix the bug: "description of the bug"

@#FIX_BUG description of the bug @#END_BUG

@#IMPROVE_PERFORMANCE / @#END_PERFORMANCE

Need to improve performance: "description of performance issue"

@#IMPROVE_PERFORMANCE description of performance issue @#END_PERFORMANCE

@#REFACTOR_CODE / @#END_REFACTOR

Need to refactor the code: "description of what to refactor "

#REFACTOR_CODE description of what to refactor @#END_REFACTOR

@#UPDATE_DEPENDENCY

"Here needs to update the dependency library_name"

@#UPDATE_DEPENDENCY library_name

@#ADD_DOCUMENTATION / @#END_DOCUMENTATION

"Need to add documentation: 'description of what needs documenting'"

@#ADD_DOCUMENTATION description of what needs documenting @#END_DOCUMENTATION

@#REMOVE_DEPRECATED / @#END_DEPRECATED

"Need to remove deprecated code: 'description of deprecated code'"

@#REMOVE_DEPRECATED description of deprecated code @#END_DEPRECATED

@#HANDLE_ERROR / @#END_ERROR

"Need to handle an error case: 'description of error'"

@#HANDLE_ERROR description of error @#END_ERROR

@#ADD_TEST / @#END_TEST

"Need to add a test case: 'description of test case'"

@#ADD_TEST description of test case @#END_TEST

Following is a link of a sample of a issue generated using step 5

Sample issue