Annotation conventions and others

[Mandatory] Comments on classes , class attributes , and class methods must use the Javadoc specification, using the /**内容*/format, and not using the // xxxmethod.
- Description: In the IDE editing window, the Javadoc method will prompt relevant comments, and the generated Javadoc can correctly output the corresponding comments; in the IDE, when the project calls a method, the meaning of the method, parameters, and return value can be suspended without entering the method, which improves reading effectiveness.
[Mandatory] All abstract methods (including methods in interfaces) must be annotated with Javadoc. In addition to return values, parameters, and exception descriptions, they must also indicate what the method does and what functions it implements.
- Description: For the implementation requirements of subclasses, or the precautions for invocation, please explain together.
[Mandatory] All classes must add creator and creation date.
[Mandatory] A single-line comment inside a method, start a new line above the commented statement, use // comment. Use /* */ for multi-line comments inside the method, pay attention to the alignment with the code.
[Mandatory] All enumeration type fields must have a comment describing the purpose of each data item.
[Mandatory] It is better to use Chinese comments to clarify the problem rather than "half-handed" comments in English. Proper nouns and keywords can be kept in the original English language.
- Counter example: "TCP connection timed out" is interpreted as "Transmission Control Protocol connection timed out", but understanding it is rather tedious.
[Recommended] When modifying the code, the comments should also be modified accordingly, especially the modification of parameters, return values, exceptions, core logic, etc.
- Explanation: Code and comment updates are out of sync, just like road network and navigation software updates are out of sync, if the navigation software lags seriously, the meaning of navigation will be lost.
[Reference] Comment out code sparingly. Elaborate above instead of simply commenting out. Delete if useless.
- Note: There are two possibilities for code to be commented out:
  - The logic of this code will be restored later.
  - Never use it. If there is no annotation information for the former, it is difficult to know the motivation of annotation. The latter suggests to delete it directly (the code repository saves the historical code).
[Reference] Requirements for annotations:
1. Be able to accurately reflect design ideas and code logic;
2. Being able to describe business implications enables other programmers to quickly understand the information behind the code.
  - A large piece of code without comments is like a book for the reader, and the comments are for themselves. Even after a long time, they can clearly understand the thinking at that time.
  - Annotations are also for successors, allowing them to quickly take over their own work.
[Reference] Good naming and code structure are self-explanatory , and comments strive to be concise, accurate, and expressive. Avoid an extreme of comments: too many comments, once the logic of the code is modified, it is a considerable burden to modify the comments.
- Counterexample:
```
// 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 code with clear semantics does not need additional comments.
[Reference] Special note mark, please indicate the mark person and mark time. Take care to deal with these marks in a timely manner, and frequently clean up such marks through mark scanning. Line failures sometimes originate from the code at these markers.
- TODO: (marked person, marked time, [estimated processing time])
  - Indicates a feature that needs to be implemented, but has not yet been implemented.
  - This is actually a Javadoc tag, which is not currently implemented in Javadoc, but is widely used. Can only be applied to classes, interfaces and methods (as it is a Javadoc tag).
- Error, can't work (FIXME): (marked person, marked time, [estimated processing time])
  - Marking a code with FIXME in a comment is wrong, doesn't work, and needs to be corrected in a timely manner.
[Mandatory] When using regular expressions, make good use of its pre-compilation function, which can effectively speed up regular expressions.
- Don't define in the method body:Pattern pattern = Pattern.compile(规则);
[Mandatory] When velocity calls the properties of POJO class, it is recommended to directly use the property name to get the value. The template engine will automatically call POJO according to the specification getXxx(). If it is a booleanbasic data type variable (boolean name does not need to be prefixed with is), it will be called automatically. isXxx() method.
- Note that if it is a Boolean wrapper class object, the getXxx() method is called first.
[Mandatory] The variables sent to the page in the background must be added with $!{var} - an exclamation mark in the middle.
- If var=null or does not exist, then ${var} will be displayed directly on the page.
[Mandatory] Note that the return type of Math.random()this method is the doubletype, and the range of the value is 0≤x<1 (zero value can be obtained, pay attention to the exception of division by zero).
- If you want to get a random number of integer type, instead of multiplying x by 10 and then rounding it, use the Random object's nextIntor `nextLong method directly.
[Mandatory] Get the current milliseconds System.currentTimeMillis();instead ofnew Date().getTime();
- If you want to get a more precise nanosecond time value, use ystem.nanoTime()the method. In JDK8, classes are recommended for scenarios such as counting time Instant.
[Recommended] Don't add any complex logic to the view template.
- According to MVC theory, the responsibility of the view is to display, not to steal the work of the model and controller.
[Recommended] The construction or initialization of any data structure should specify a size to avoid the infinite growth of the data structure eating up memory.
[Recommended] Clean up code segments or configuration information that are no longer used in a timely manner.
- Note: For junk code or outdated configuration, resolutely clean it up to avoid overly bloated programs and redundant code.
- Positive example: For code snippets that are temporarily commented out and may be resumed later, above the commented code, three slashes (///) are uniformly specified to explain the reason for commenting out the code.

Java Coding Convention 8 (Programming Conventions - Annotation Conventions and Others)

Annotation conventions and others

Guess you like