guide_to_comments_in_project_the_code
Differences
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 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: |
| - | 2- 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 | // 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 1 |
| + | 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 | + | |
| - | 5- 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> | ||
guide_to_comments_in_project_the_code.1737046002.txt.gz · Last modified: 2025/01/16 16:46 by serradfh
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
