What kind of range space do you think is the ratio of comments to codes? Can it be the byte or the number of lines?

Source: Internet
Author: User
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)
......
})
  1. Construct an ordered array, initially empty
  2. Loop the entire array and perform the following operations:
  3. From the elements left in the arraySelectMinimum (or maximum)
  4. 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.

Contact Us

The content source of this page is from Internet, which doesn't represent Alibaba Cloud's opinion; products and services mentioned on that page don't have any relationship with Alibaba Cloud. If the content of the page makes you feel confusing, please write us an email, we will handle the problem within 5 days after receiving your email.

If you find any instances of plagiarism from the community, please send an email to: info-contact@alibabacloud.com and provide relevant evidence. A staff member will contact you within 5 working days.

A Free Trial That Lets You Build Big!

Start building with 50+ products and up to 12 months usage for Elastic Compute Service

  • Sales Support

    1 on 1 presale consultation

  • After-Sales Support

    24/7 Technical Support 6 Free Tickets per Quarter Faster Response

  • Alibaba Cloud offers highly flexible support services tailored to meet your exact needs.