3 ms·
Generally, he is right. But he gets this point wrong: > Comments are the only way to capture the intent of the code at the time of writing. The main and most
by Hermel 14y ago
Generally, he is right. But he gets this point wrong:
> Comments are the only way to capture the intent of the code at the time of writing.
The main and most important way to express intent is meaningful naming of variables, fields, and methods. A declaration like "String username" conveys much more intent than "String x". Similarily, if you have a block of code that needs a comment, you should first move it into a separate method with a good name. Then, if it still needs commenting, you should comment on that method.
Also, with comments, it is like everything that improves your code: there is a tradeoff between effort and effect. If you have one hour to improve your code, where do you invest it? Cleaner structure? Better namings? More comments? More tests? UML-Diagrams? Flow charts? Other documentation? Adding features? Something else? Comments are unlikely to take the top spot here.
- Joeri 14y agoI don't agree with this definition of intent. For me intent is about why a piece of code is written the way that it is, which is also what the article itself equates it to. Also, I don't think you can write many useful comments when returning to a piece of already written code. The only way to understand the why of a piece of code is to trace all its implications, and it is not efficient to make that sort of investment after the fact. The easiest way to produce high quality comments is to write them during the act of programming.