Annotation convention
1. [Mandatory] Comments on classes, class attributes, and class methods must use Javadoc specifications and use the /**content*/ format. // xxx format is not allowed.
Note: In the IDE editing window, the Javadoc mode will prompt relevant comments, and the generated Javadoc can correctly output the corresponding comments; In the IDE, when the project calls a method , you can hover prompts about the meaning of methods, parameters, and return values without entering the method, improving reading efficiency.
2. [Mandatory] All abstract methods (including methods in interfaces) must be commented with Javadoc, except return values, parameters, and exceptions In addition to the description, it must also be pointed out what the method does and what functions it implements.
Note: Please explain the implementation requirements for subclasses or calling precautions.
#3. [Mandatory] All classes must add creator information.
#4. [Mandatory] Single-line comments inside the method, start a new line above the commented statement, and use // comment. Multi-line comments inside the methodUse /* */ comments, pay attention to align with the code.
5. [Mandatory] All enumeration type fields must have comments to explain the purpose of each data item.
6. [Recommendation] Rather than commenting in half-baked English, it is better to use Chinese comments to explain the problem clearly. Proper nouns and keywords can remain in the original English text.
Counter example: "TCP connection timeout" is interpreted as "Transmission Control Protocol connection timeout", which is more troublesome to understand.
7. [Recommendation] When modifying the code, comments should also be modified accordingly, especially modifications to parameters, return values, exceptions, core logic, etc. .
Note: Code and annotation updates are out of sync, just like road network and navigation software updates are out of sync. If the navigation software lags seriously, will lose the ability to navigate. significance.
#8. [Reference] The commented out code should be accompanied by instructions as much as possible, rather than simply commented out.
Note: There are two possibilities for the code to be commented out: 1) The logic of this code will be restored later. 2) Never use it. If there is no remark information in the former, it is difficult to know the motivation of the annotation. The latter is recommended to be deleted directly (the code warehouse saves historical code).
9. [Reference] Requirements for comments: First, they can accurately reflect the design ideas and code logic; Second, they can describe the business meaning, so that other programmers can quickly understand the information behind the code. . A large section of code without comments at all is like a bible to the reader. Comments are for oneself to read. Even after a long time, one can clearly understand the thinking at that time; comments are also for successors to read , so that it can quickly take over its own work.
#10. [Reference] Good naming and code structure are self-explanatory, and comments should be concise, accurate, and expressive. Avoid the
extreme of comments: too many and excessive comments. Once the logic of the code is modified, modifying the comments is a considerable burden.
Counter example:
// put elephant into fridge put(elephant, fridge);The method name put, plus two meaningful variable names elephant and bridge, have already explained what this is doing, and the language Clearly defined code does not require additional comments.
#11. [Reference] Special comment mark, please indicate the person who marked it and the time of marking. Pay attention to handling these marks in a timely manner, and clean such marks frequently through mark scanning. Online faults sometimes originate from the code at these marks.
1) To-do items (TODO): (mark person, mark time, [estimated processing time])
indicates that it needs to be implemented, but it is not yet available Unimplemented functionality. This is actually a Javadoc tag. The current Javadoc has not yet been implemented, but it is already widely used. Can only be applied to classes, interfaces and methods (because it is a Javadoc tag).
2) Error, not working (FIXME): (Mark person, mark time, [estimated processing time])
Mark with FIXME in comments A situation where a certain code is wrong and does not work and needs to be corrected promptly.
