Why do I refuse to write comments?

In fact, no one asked me why I didn't write comments, and I didn't tell anyone why I didn't write comments. However, some people have been saying in my ear recently that you are not writing comments. So I think it is necessary to explain it.

First, under what circumstances do you need to comment out. If you are facing an audience of beginners or non-professionals, you do need to write comments, which is the most obvious in textbooks. Or, the language you work on is structured programming and other languages that do not have a strong hierarchy (package or namespace) or encapsulation (class ), then you need to write comments (C is the best example ). Finally, if you are writing an algorithm or your function has a magic number, you need to add comments. For example, if you have a function as follows, you 'd better write some comments.

Public String getrequestfile (){
If (string. isnullorempty (request. querystring ["FILENAME"])
Return magicfilename; // you may need to explain why such a file name is returned.
Normal procedure ....
}

.

Second, why don't I write comments. First of all, I am dealing with professional people who are working on software and may not be able to understand it. Second, the current project language is C #, object-oriented, and well encapsulated. There are not many lines of code for a class (because of a single responsibility ). Finally, functions and classes are self-explanatory, which is relatively simple and easy to understand. (the number of functions I write generally does not exceed 10. If the exception is handled a little more, there will be 20 rows, the function name and class name are also compliant, and the class generally does not exceed 150 rows ).

Third, why do I need annotations. 1. The program is poorly written, and the function and class names are not self-explanatory (or language-related, such as C ). 2. The code reader is not familiar with the business (it is recommended that you be familiar with the business first, because the business is fundamental and the technology is only implemented ). 3. Limited code readers or their own experiences lead to comments.

However, the person who asked me to write comments belongs to 3. He is transferred from PHP, and his code style is purely process-oriented. Many comments are written to the program, but it is also very long. It is often done by one or two functions on a page, 300 rows are common. Therefore, he has developed a bad habit of reading a program. He always needs to read the program to understand what the class is. (class name and function name are full of clouds for him, getrequestfile and getresponefile should have no difference ). In most cases, we look at the code. The first is the class name, and the second is the name of the called function (public method). Generally, it is enough to judge what this class is doing and what functions it provides (if not, you can tell the author of the class to rebuild it. It's hard for me to see it ). This requires us to write code like writing a poem. Even if it doesn't work, we should at least implement self-interpretation of the Code. Therefore, if you are a person who refuses to write comments, do the code you write meet the requirements of the first and second levels?

The class to be annotated is probably like this.

 

Class userauth {
Public bool userloginasclient (){
......
}
Public bool userloginasmanager (){
......
} Another private function
}