Ptidej Team

Guide to comment in the code of PTIDEJ Project

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

// 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

Known bugs

If the step 5 is used to generate the title, and inside a comment is used more than one same Id, if a "// TODO" is not used before every next same Id, will not count towards the title

Example 1

// TODO
// @#REFACTOR_CODE Handle a uniform encoding? 4 @#END_REFACTOR
// the one above was added in the title
// TODO
// @#REFACTOR_CODE Handle a uniform encoding? 5 @#END_REFACTOR
// the one above was added in the title

Title output of example 1

Testing on ProxyDisk.java -> 2 Refactor Codes

Example 2

// TODO
// @#REFACTOR_CODE Handle a uniform encoding? 4 @#END_REFACTOR
// the one above was added in the title
// @#REFACTOR_CODE Handle a uniform encoding? 5 @#END_REFACTOR
// will not be added to the title

Title output of example 2

Testing on ProxyDisk.java -> 1 Refactor Codes

Example 3

// TODO
// @#REFACTOR_CODE Handle a uniform encoding? 4 @#END_REFACTOR
// @#REFACTOR_CODE Handle a uniform encoding? 5 @#END_REFACTOR
// only the first one counted here
some_method()
// TODO
// @#REFACTOR_CODE Handle a uniform encoding? 6 @#END_REFACTOR

Title output of example 3

Testing on ProxyDisk.java -> 2 Refactor Codes