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:46]
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.
  
-1- The first line of comment is always"// TODO"+It will read and generate title, tags, descriptions and semantics automatically in the following order:
  
-2To keep same issue after step 1, keep using "//"​ in the next lines +----- 
-Correct:+=====- The first line of comment is always ​the following=====
  
-// TODO+<​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 // 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 26: Line 38:
 // something else // something else
 method(); method();
- +</​code>​ 
-Two TODO: +==Two TODO== 
 +<​code>​
 // TODO // TODO
 // something // something
Line 34: 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.1737046002.txt.gz · Last modified: 2025/01/16 16:46 by serradfh