Differences

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

--- guide_to_comments_in_project_the_code [2025/01/16 16:46] – created 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.
+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>