Differences

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

--- 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.
-- The first line of comment is always: "// TODO"
+It will read and generate title, tags, descriptions and semantics automatically in the following order:
-- To keep same issue after step 1, keep using "//" in the next lines
+-----
-Correct:
+=====1 - 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
 someMethod()
+</code>
-Wrong:
+==Wrong==
-// TODO
+<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=====
-- 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`
 // something
@@ Line 26: / Line 38: @@
 // something else
 method();
+</code>
-Two TODO:
+==Two TODO==
+<code>
 // TODO
 // something
@@ Line 34: / Line 46: @@
 // TODO
 // something else
+</code>
-- 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 1
+method();
+// TODO
+// something of the issue 2
 // 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
-- Following are all the ID's for these codes, what they do and how to use respectively:
+=====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=====
-@#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>