4 ms·
> Comments are mostly useless in a machine-generated and machine-consumed file. They are indispensable for humans, because they are a link to what machines are
by breck 8y ago
> Comments are mostly useless in a machine-generated and machine-consumed file. They are indispensable for humans, because they are a link to what machines are not doing.
But comments are often code smell—a crutch for poor identifier naming and design. If your names and design are well thought out you rarely need comments and the consumer of your code should be able to understand it using the statically checked source alone—-versus manually having to parse your unchecked human language documentation.
- j88439h84 8y ago> If your names and design are well thought out Sure, but how often does that happen?
- breck 8y agoIt usually happens in good code if the language supports it. But I agree, not enough and comments are great as a stopgap until the thing you need to explain can be explained in the programming language. But sometimes that can’t be and so you do need to resort to comments. It’s like types in doc comments being used as a stopgap until a language added types. I hypothesize (I plan at some point to crunch some data here) the more comments the worse the language, and so you’d see a pattern like Python 3 code having fewer comments on average than Python 2 code.
- breck 8y agoEdit: adding a link to the Clean Code bit about comments, which I think is great advice : https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988cf8d29#comments-rules https://gist.github.com/wojteklu/73c6914cc446146b8b533c0988c...
- TeMPOraL 8y agoFrom the link, about comments: Use as explanation of intent. Use as clarification of code. Use as warning of consequences. Here's a link to a well-known recent book, half of which is pretty much about why those points are a real and frequent thing, and why code should be much more thoroughly commented than it's recommended by the usual philosophies. https://www.amazon.com/Philosophy-Software-Design-John-Ousterhout/dp/1732102201 https://www.amazon.com/Philosophy-Software-Design-John-Ouste...
- nine_k 8y agoComments are a code smell when they describe things that should be described in code. Comments are important when they express things that code cannot. Examples: // See ticket XYZ-123 for discussion and rationale. // We are sidestepping a bug in Docker 3.x here. // TODO: Allow queue size per service version. Currently we're using max size for all.
- breck 8y agoGreat examples. I wonder though if all those could be better expressed using something like decorators in order to enforce some static time checks. For example, instead of a free form comment to do have a structured todo notation that then makes the todo parsible and checkable. Often I see a //todo comment that is still there by accident after the thing is done. Or a todo that has since been abandoned.
- afiori 8y agoIn a JSON config comments can be very useful to "hide" disabled options ["DoStuff", "EvenMore"/, "ops go back :("/]
- int_19h 8y agoJSON is data, not code.