Table of Contents

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

Sample issue

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