User Tools

Site Tools


guide_to_comments_in_project_the_code

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Next revision
Previous revision
guide_to_comments_in_project_the_code [2025/01/16 16:46]
serradfh created
guide_to_comments_in_project_the_code [2025/01/21 16:53] (current)
serradfh
Line 1: Line 1:
-===== Guide to comment in the code of PTIDEJ Project ​=====+===== Guide comments ===== 
 + 
 +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===== 
 + 
 +<​code>//​ TODO</​code>​ 
 + 
 +----- 
 + 
 +=====2- To continue to create the issue of step 1, keep using // in the next lines without real code of the class===== 
 + 
 +==Correct== 
 + 
 +<​code>​ 
 +// TODO  
 +// same issue comment 
 +someMethod() 
 +</​code>​ 
 +==Wrong== 
 +<​code>​ 
 +// TODO  
 +someMethod() 
 +// same issue comment 
 +</​code>​ 
 +----- 
 +=====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== 
 +<​code>​ 
 +// TODOx` 
 +// something 
 +// TODO 
 +// something else 
 +method(); 
 +</​code>​ 
 +==Two TODO== 
 +<​code>​ 
 +// TODO 
 +// something 
 +method(); 
 +// TODO 
 +// something else 
 +</​code>​ 
 +==Three TODO== 
 +<​code>​ 
 +// 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 
 + 
 +</​code>​ 
 + 
 +====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()"​ 
 +<​code>​ 
 +// TODO 
 +// @#​ADD_METHOD some_method() 
 +</​code>​ 
 + 
 +==Result of example 1 in FAST DESCRIPTION== 
 +<​code>​ 
 +- The method some_method() needs to be added 
 +</​code>​ 
 +==Result of example 1 in the TITLE== 
 +<​code>​ 
 +Some_Library on File_Name.java -> 1 Add Method 
 +</​code>​ 
 +==Result of example 1 TITLE if not used the @#​ADD_METHOD== 
 +<​code>​ 
 +Some_Library on File_Name.java 
 +</​code>​ 
 +------ 
 +=====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"​== 
 +<​code>​@#​ADD_METHOD something_method()</​code>​ 
 +------- 
 +===@#​REMOVE_METHOD=== 
 +=="​Here needs to remove this method"​== 
 +<​code>​@#​REMOVE_METHOD something_method()</​code>​ 
 +------- 
 +===@#​ADD_CONSTANT=== 
 +=="​Here needs to add this constant"​== 
 +<​code>​@#​ADD_CONSTANT SOME_CONSTANT</​code>​ 
 +------- 
 +===@#​REMOVE_CONSTANT=== 
 +=="​Here needs to remove this constant"​== 
 +<​code>​@#​REMOVE_CONSTANT SOME_CONSTANT</​code>​ 
 +------- 
 +===@#​FIX_BUG / @#​END_BUG=== 
 +==Need to fix the bug: "​description of the bug" ​ == 
 +<​code>​@#​FIX_BUG description of the bug @#​END_BUG</​code>​ 
 +------- 
 +===@#​IMPROVE_PERFORMANCE / @#​END_PERFORMANCE=== 
 +==Need to improve performance:​ "​description of performance issue" ​ == 
 +<​code>​@#​IMPROVE_PERFORMANCE description of performance issue @#​END_PERFORMANCE</​code>​ 
 +------- 
 +===@#​REFACTOR_CODE / @#​END_REFACTOR=== 
 +==Need to refactor the code: "​description of what to refactor " ​ == 
 +<​code>#​REFACTOR_CODE description of what to refactor @#​END_REFACTOR</​code>​ 
 +------- 
 +===@#​UPDATE_DEPENDENCY=== 
 +=="​Here needs to update the dependency library_name"​== 
 +<​code>​@#​UPDATE_DEPENDENCY library_name</​code>​ 
 +------- 
 +===@#​ADD_DOCUMENTATION / @#​END_DOCUMENTATION=== 
 +=="​Need to add documentation:​ '​description of what needs documenting'"​== 
 +<​code>​@#​ADD_DOCUMENTATION description of what needs documenting @#​END_DOCUMENTATION</​code>​ 
 + 
 +------- 
 +===@#​REMOVE_DEPRECATED / @#​END_DEPRECATED=== 
 +=="​Need to remove deprecated code: '​description of deprecated code'"​== 
 +<​code>​@#​REMOVE_DEPRECATED description of deprecated code @#​END_DEPRECATED</​code>​ 
 +------- 
 +===@#​HANDLE_ERROR / @#​END_ERROR=== 
 +=="​Need to handle an error case: '​description of error'"​== 
 +<​code>​@#​HANDLE_ERROR description of error @#​END_ERROR</​code>​ 
 +------- 
 +===@#​ADD_TEST / @#​END_TEST=== 
 +=="​Need to add a test case: '​description of test case'"​== 
 +<​code>​@#​ADD_TEST description of test case @#​END_TEST</​code>​ 
 + 
 +====Following is a link of a sample of a issue generated using step 5==== 
 +[[https://​github.com/​agadfs/​Git_PTIDEJ_Issue_Organizer/​issues/​121|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== 
 +<​code>​ 
 +// 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 
 +</​code>​ 
 +==Title output of example 1== 
 +<​code>​ 
 +Testing on ProxyDisk.java -> 2 Refactor Codes 
 +</​code>​ 
 +==Example 2== 
 +<​code>​ 
 +// 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 
 +</​code>​ 
 +==Title output of example 2== 
 +<​code>​ 
 +Testing on ProxyDisk.java -> 1 Refactor Codes 
 +</​code>​ 
 + 
 +==Example 3== 
 +<​code>​ 
 +// 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 
 +</​code>​ 
 +==Title output of example 3== 
 +<​code>​ 
 +Testing on ProxyDisk.java -> 2 Refactor Codes 
 +</​code>​ 
 + 
guide_to_comments_in_project_the_code.1737045972.txt.gz · Last modified: 2025/01/16 16:46 by serradfh