0 reply content: according to the national standard, the VC project annotation rate is 25% ~ 50%. The critical code comment rate is 50%;
Third-party software evaluation fails if the requirements are not met;
When this requirement is met, we will discuss which annotations are required.
To increase the code comment rate and reduce the pain of "brain supplement" comments before the third-party evaluation,
We generally require that the "key algorithms" and "interface data definitions" in the software design document be directly copied to the front of the Code;
The comments of key algorithms and interface data definitions are also modified when the code is modified;
When revising the software design document, replace the relevant content in the document with "key algorithms" and "interface data definition" in the notes;
This method ensures document and code consistency and reduces the pain points of software maintenance and personnel replacement ...... My point of view,
Write descriptive comments only, do not write functional comments. That is to say, comment Why instead
How and What.
Write multiple classes and functions
Document commentIt doesn't matter how many lines, as long as you are commenting on Why.
Write as few comments as possible within the function. If your code needs to write comments to describe its functions, then this code requires
Reconstruction, The simplest method, the simplest method:
Extract Functions. The benefit is that the function name is annotation. A wrong idea is:
Comments are for people, and programs are for computers.. In fact, the program is for humans. Coincidentally, it can run on a computer.
Reconstruction: improving the design of existing code
The book writes:
Whenever we feel that we need to annotate something, we write the things to be explained into an independent function and name it for its purpose (rather than implementation method )..
Every time I explain "select sort" and "insert sort" to others, they all think it is too difficult, and almost every data structure textbook writes a bunch of code and comments, this does not reduce the difficulty of this algorithm.
What if I write a function without writing comments?
Pseudocode:
Array_ordered = []
Loop_all_element (array, function (I ){
El = select (array [I + 1, array. length])
Push (array_ordered, el)
......
})
- Construct an ordered array, initially empty
- Loop the entire array and perform the following operations:
- From the elements left in the arraySelectMinimum (or maximum)
- Place the minimum element at the end of the ordered array (or at the beginning)
You can see it at a glance.
Select sort.
What about insert sorting? I will not elaborate on it.
So,
Document comments. Comments in the function and in the class. If this parameter can be left blank, no comments will be written.. I think so. It depends on the role of the code you write.
1. Simple code or scripts follow the naming rules. You can leave comments blank and the file starts to indicate the purpose. Write simple comments to the key part.
2. A complex project structure composed of multiple files. The description of the file should be generated by a tool, and the input and output of the class method should be indicated.
3. If it is an open-source project, the situation is completely different. The more comments, the better. The more comments, the better.
The above is my understanding. Please correct PHP itself without any comments.
Just keep the variable naming standard.
A description can be provided for each method at most.
