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

Both sides previous revision Previous revision
Next revision
Previous revision
guide_to_comments_in_project_the_code [2025/01/16 16:52]
serradfh
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. 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 parse and generate title, tags, descriptions and semantics automatically in the following order:+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=====
  
-1- The first line of comment is always: ​+<​code>//​ TODO</​code>​
  
-`// TODO`+-----
  
-2- To keep same issue after step 1, keep using "//" ​in the next lines +=====2- To continue to create the issue of step 1, keep using // in the next lines without real code of the class=====
-Correct:+
  
-// TODO+==Correct== 
 + 
 +<​code>​ 
 +// TODO 
 // same issue comment // same issue comment
 someMethod() someMethod()
- +</​code>​ 
-Wrong: +==Wrong== 
-// TODO+<​code>​ 
 +// TODO 
 someMethod() someMethod()
 // same issue comment // 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=====
  
  
-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>​
-One TODO: +
 // TODOx` // TODOx`
 // something // something
Line 32: Line 38:
 // something else // something else
 method(); method();
- +</​code>​ 
-Two TODO: +==Two TODO== 
 +<​code>​
 // TODO // TODO
 // something // something
Line 40: Line 46:
 // TODO // TODO
 // something else // something else
- +</​code>​ 
-4- Inside any TODO, add certain codes in the middle of the comment to create context to the issue reader +==Three ​TODO== 
- +<​code>​ 
-Example ​1 +// TODO 
-@#​ADD_METHOD = Add a method+// something of issue 
 +method(); 
 +// TODO 
 +// something of the issue 2
  
 // TODO // TODO
-// @#​ADD_METHOD some_method()+// something of the issue 3 
 +// TODO 
 +// something else of the issue 3
  
 +</​code>​
  
-Result of example 1: +====Next steps are optional but highly encouraged ​to give the issues FAST DESCRIPTION and a precise TITLE====
-"The method some_method() needs to be added+
  
-5Following are all the ID's for these codes, what they do and how to use respectively:​+=====4To 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=====
  
-@#​ADD_METHOD = Add a method ​=`@#​ADD_METHOD ​something_method()`+==Example 1== 
 +@#​ADD_METHOD = "Here needs to add this method ​some_method()"​ 
 +<code> 
 +// TODO 
 +// @#​ADD_METHOD ​some_method() 
 +</​code>​
  
-@#REMOVE_METHOD ​Remove a method ​=> `@#REMOVE_METHOD something_method()`+==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_CONSTANT = Add a constant => `@#​ADD_CONSTANT SOME_CONSTANT` +===@#​ADD_METHOD=== 
- +=="​Here needs to add this method"​== 
-@#​REMOVE_CONSTANT = Remove a constant => `@#​REMOVE_CONSTANT SOME_CONSTANT` +<​code>​@#​ADD_METHOD something_method()</​code>​ 
- +------- 
-@#FIX_BUG / @#END_BUG = Fix a bug => `@#FIX_BUG description of the bug @#END_BUG` +===@#​REMOVE_METHOD=== 
- +=="​Here needs to remove this method"​== 
-@#​IMPROVE_PERFORMANCE / @#​END_PERFORMANCE = Improve ​performance => `@#​IMPROVE_PERFORMANCE description of performance issue @#​END_PERFORMANCE` +<​code>​@#​REMOVE_METHOD something_method()</​code>​ 
- +------- 
-@#​REFACTOR_CODE / @#​END_REFACTOR = Refactor ​the code => `@#​REFACTOR_CODE description of what to refactor @#​END_REFACTOR` +===@#​ADD_CONSTANT=== 
- +=="​Here needs to add this constant"=
-@#​UPDATE_DEPENDENCY = Update a dependency => `@#​UPDATE_DEPENDENCY library_name` +<code>​@#​ADD_CONSTANT SOME_CONSTANT</​code>​ 
- +------- 
-@#​ADD_DOCUMENTATION / @#​END_DOCUMENTATION = Add documentation ​=> `@#​ADD_DOCUMENTATION ​description of what needs documenting+===@#​REMOVE_CONSTANT=== 
- +=="​Here needs to remove this constant"=
-@#​REMOVE_DEPRECATED / @#​END_DEPRECATED ​Remove deprecated code => `@#​REMOVE_DEPRECATED description of deprecated code` +<code>​@#​REMOVE_CONSTANT SOME_CONSTANT</​code>​ 
- +------- 
-@#​HANDLE_ERROR / @#END_ERROR = Handle an error case =`@#HANDLE_ERROR ​description of error` +===@#FIX_BUG / @#END_BUG=== 
- +==Need to fix the bug: "​description of the bug"  ​=
-@#ADD_TEST ​@#END_TEST = Add a test case =`@#ADD_TEST description of test case`+<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.1737046362.txt.gz · Last modified: 2025/01/16 16:52 by serradfh