In the world of software development, writing code comments and documentation is often considered an important job that helps other developers understand your code and maintain and extend it more easily. In practice, however, many programmers choose not to write comments or documentation. The following is a list of ten reasons that programmers often mention in practice. These reasons not only reveal their views on writing documentation and comments, but also reflect some deep problems in the software development industry.
-
We're not developing an externally facing SDK, so documentation seems unnecessary. Furthermore, writing documentation is not part of the KPI.
-
In fact, it was because the deadline was too tight. I'm even willing to add unit tests if I have enough time. But the reality is that as soon as a project is completed, new tasks follow immediately, and there is no time for us to take a break.
-
Sometimes, we do have documentation, but it's not up to date and it's all outdated. In this case, it is better to have no documentation than to have no documentation. It is often better to look at the code directly than to consult the documentation, but it makes people mistakenly think that it is very convenient to have documentation.
-
In my code, I hardly write comments. I will write API documents in the wiki, code specification, and naming specification. When your code is standardized and named, there is actually no need to write comments. Directory names, function names, and variable names are the best comments.
-
If your architecture is well designed, the code is easy to read, and easy to expand, anyone can take over. This makes you a "dispensable" person.
-
If your code is well written, there are basically no bugs, and you don't need to work overtime every day, you will be regarded as a person with a negative work attitude.
-
If your code is poorly written, bugs keep popping up, and you have to work overtime every day, you become the backbone of the company.
-
If your architecture is such a mess that no one else touches your code but yourself, then you are important to the company, and without you, the project will collapse.
-
When writing documents and comments, you need to be considerate of the developer's feelings. During normal development hours, we need at least half of the time to write documents. If you don't have this time, you can't write naturally, there is no doubt about it.
-
Notes are written for future reference, not for those who follow up. If you can understand it yourself, there is no need to write comments. The principle of code is: code that can be understood without comments is the best code.
The above are the top ten reasons why programmers do not write code comments and documents. These reasons fully reflect their troubles and pressures in actual work. However, this does not mean that we can ignore the importance of documentation and comments. Although in some cases, these reasons may have some truth, but good code comments and comprehensive documentation can undoubtedly make our work more efficient and make it easier for other developers to understand and maintain our code. To this end, we need to find a balance point to meet the needs of the project while reducing the burden on developers as much as possible.