About comments in the code say a word
A post appeared, in the comments to which (how ironic) there were many opinions,
that the best code is self-documenting and all that.
I, in general, do not pretend to be a guru and only present my own opinion below. It differs from the opinion that the best comment is the one that did not exist, but contains practical arguments behind it.
In the post I will briefly tell you how I have been using comments in my development for 10 years and will smoothly touch upon the topic of documentation in general.
')
Artemy Lebedev (master of outrageous IMHO) has such a rule - he knows his way of thinking. And if you forgot something, for example, where the photo you want lies, then your knowledge of the categorization system allows you to quickly find the photo you want.
Same with comments. I have projects that have not been touched for many years. You open this project in the IDE, drive in a few words, and find the necessary files and classes without effort. I mean, the first topic is to write what at least each file does at the very beginning. Very saves search time. And when there are also tests - the search is simplified completely.
This is how IDEs are arranged, that they keep all kinds of javadoc in memory. And when you write a new code, tooltips make life much easier, explaining what and how. Especially when a team is working on a project, and you use third-party methods.
I do not know about you, but I always liked the documentation, which is generated from the comments, as a reference book. It is really convenient to look at a particular method in another library, without opening the code entirely, when you are designing something.
After a year, I liked the expression “laziness is the engine of progress”. I think a lazy programmer or admin is an innate and useful quality.
By laziness, I mean the intuitive desire not to do the same work more than a finite number of times. For example, three times butnuv Apache, the fourth good admin will solve the problem, or automates the process. Or, for the fourth time, ruling the config on five servers, will install an automatic server for configs on servers. Without this quality, the admin will do the routine every time.
When I was given several loaded projects where the questions of developers were very frequent, I began to apply the principle of three nails. After each third question I wrote a FAQ for every typical question, for each task I’ve a tutorial with comments in the tutoril code.
Six months later, I responded to 80% with links to tutorials and FAQs and did not get out of the stream , although the number of my subordinates grew on projects from two to five.
If you work alone, if you have plenty of time, if you don’t do projects on an industrial scale, then you can write beautiful self-documenting code. I did this in my handicrafts for the time being.
You can write good readable code, but comments are useful for the perception of the project as a whole and for solving practical problems outlined above.
If you work in a team, you have projects that grow to> 100,000 lines of code, and you will be returning to them in a couple of years - comments are simply necessary for you. At least at the level that this or that file does, this or that big important piece of logic.
And of course, do not forget about the effect of Dannig-Kruger . A person can consider his code readable and understandable, but not the fact that this is so for others.
Especially important after accepting projects from noobs , who read McConnell about the self-documenting code and remembered that there was no need to write comments, and all other recommendations for code design and code conventions ignored completely - or, God forbid, freelance order from the past to support Hindu site).
And if you are still a Senior Team Lead developer, and your responsibilities also include working with non-technical people, or working with newbies, then the documentation, which is scaled up along the evolutionary on-demand principle to increase, hit cache, so to speak, will be a significant saving of your time.
Links to the topic
1. There is no such thing as self-documenting code - it's a mys
2. Bloated names, self-documenting code
3. Intent versus action, or the myth of self-documenting code
4. Self Documenting Code
that the best code is self-documenting and all that.
I, in general, do not pretend to be a guru and only present my own opinion below. It differs from the opinion that the best comment is the one that did not exist, but contains practical arguments behind it.
In the post I will briefly tell you how I have been using comments in my development for 10 years and will smoothly touch upon the topic of documentation in general.
')
Comments help find forgotten code
Artemy Lebedev (master of outrageous IMHO) has such a rule - he knows his way of thinking. And if you forgot something, for example, where the photo you want lies, then your knowledge of the categorization system allows you to quickly find the photo you want.
Same with comments. I have projects that have not been touched for many years. You open this project in the IDE, drive in a few words, and find the necessary files and classes without effort. I mean, the first topic is to write what at least each file does at the very beginning. Very saves search time. And when there are also tests - the search is simplified completely.
Comments help develop in IDE
This is how IDEs are arranged, that they keep all kinds of javadoc in memory. And when you write a new code, tooltips make life much easier, explaining what and how. Especially when a team is working on a project, and you use third-party methods.
Comments help in creating documentation
I do not know about you, but I always liked the documentation, which is generated from the comments, as a reference book. It is really convenient to look at a particular method in another library, without opening the code entirely, when you are designing something.
Documentation at all
After a year, I liked the expression “laziness is the engine of progress”. I think a lazy programmer or admin is an innate and useful quality.
By laziness, I mean the intuitive desire not to do the same work more than a finite number of times. For example, three times butnuv Apache, the fourth good admin will solve the problem, or automates the process. Or, for the fourth time, ruling the config on five servers, will install an automatic server for configs on servers. Without this quality, the admin will do the routine every time.
When I was given several loaded projects where the questions of developers were very frequent, I began to apply the principle of three nails. After each third question I wrote a FAQ for every typical question, for each task I’ve a tutorial with comments in the tutoril code.
Six months later, I responded to 80% with links to tutorials and FAQs and did not get out of the stream , although the number of my subordinates grew on projects from two to five.
Conclusion
If you work alone, if you have plenty of time, if you don’t do projects on an industrial scale, then you can write beautiful self-documenting code. I did this in my handicrafts for the time being.
You can write good readable code, but comments are useful for the perception of the project as a whole and for solving practical problems outlined above.
If you work in a team, you have projects that grow to> 100,000 lines of code, and you will be returning to them in a couple of years - comments are simply necessary for you. At least at the level that this or that file does, this or that big important piece of logic.
And of course, do not forget about the effect of Dannig-Kruger . A person can consider his code readable and understandable, but not the fact that this is so for others.
Especially important after accepting projects from noobs , who read McConnell about the self-documenting code and remembered that there was no need to write comments, and all other recommendations for code design and code conventions ignored completely - or, God forbid, freelance order from the past to support Hindu site).
And if you are still a Senior Team Lead developer, and your responsibilities also include working with non-technical people, or working with newbies, then the documentation, which is scaled up along the evolutionary on-demand principle to increase, hit cache, so to speak, will be a significant saving of your time.
Links to the topic
1. There is no such thing as self-documenting code - it's a mys
2. Bloated names, self-documenting code
3. Intent versus action, or the myth of self-documenting code
4. Self Documenting Code
Source: https://habr.com/ru/post/183108/
All Articles