5 ms·
Agreed, with one caveat: even better than explanatory comments are explanatory method and variable names, when possible. For example, you could have one 10-lin
by nathan_long 14y ago
Agreed, with one caveat: even better than explanatory comments are explanatory method and variable names, when possible.
For example, you could have one 10-line method, interspersed with comments, or you could have a hierarchy of method calls, each with a name so clear that it needs no comments. The second method is less likely to get out of sync with what the code actually does, and it's more testable.
This the lesson that stuck with me most from Clean Code, which I highly recommend.
- wikwocket 14y agoEven better is naming things as intuitively as possible, and to use explanatory comments where they would be helpful. Not trying to pick on you, but every time I see someone implying that "naming things better" is a panacea, I want to throw it out there that sometimes, nothing beats a good comment to explain (in natural language) what's going on here.
- nathan_long 14y agoWe're on the same page. Generally, I find that naming things better helps explain what the program is doing, and comments help explain why. And comments will stand out best if they are only used when needed to answer the question "why didn't they just..." :)