This shows you the differences between two versions of the page.
Both sides previous revision Previous revision Next revision | Previous revision | ||
guide_to_comments_in_project_the_code [2025/01/16 17:48] serradfh Guide to properly comment and use the issue reader |
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. | ||
Line 6: | Line 6: | ||
----- | ----- | ||
- | ===1 - The first line of comment is always the following=== | + | =====1 - The first line of comment is always the following===== |
<code>// TODO</code> | <code>// TODO</code> | ||
Line 12: | Line 12: | ||
----- | ----- | ||
- | ===2- To continue to create the issue of step 1, keep using // in the next lines without real code of the class=== | + | =====2- To continue to create the issue of step 1, keep using // in the next lines without real code of the class===== |
==Correct== | ==Correct== | ||
Line 28: | Line 28: | ||
</code> | </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===== |
Line 64: | Line 64: | ||
====Next steps are optional but highly encouraged to give the issues FAST DESCRIPTION and a precise TITLE==== | ====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=== | + | =====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== | ==Example 1== | ||
Line 86: | Line 86: | ||
</code> | </code> | ||
------ | ------ | ||
- | ====5- Following are all the ID's for these codes, what they mean and how to use respectively==== | + | =====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== | ==If the ID code has a @#END_, any text in the middle of the start and the @#END_, will be used in the description== | ||
Line 140: | Line 140: | ||
====Following is a link of a sample of a issue generated using step 5==== | ====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]] | [[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> | ||