“My Code is Self-Documenting”
ericholscher.com
“My Code is Self-Documenting”
1–10 of 100 posts
Re: “My Code is Self-Documenting”
#2I find that the commonly touted opinion that comments should only reflect why, and avoid all duplication; is misguided. The only places where I will elaborate on why is where I can see obvious room for improvement but I'm still waiting for the bigger picture to stabilize, or I'm adding a dependency that I'm not really happy with. Otherwise my comments mostly express the intent of the code in regular prose and have to be updated with the code.
Re: “My Code is Self-Documenting”
#3> Code comments document the why, not the how.
I disagree. The _what_ is what your comments should tell me. The contract, and its preconditions and postconditions. Nothing more, nothing less.
Re: “My Code is Self-Documenting”
#4The biggest problem I have with comments is that they quickly fall out of sync with the code. The code gets updated but the comments stay the same. Now you have a situation worse than no comments: misleading comments.
It sometimes happens with self-documenting code too, but only when someone refactors enough of the code so that the class or method no longer matches the original name.
Re: “My Code is Self-Documenting”
#5The biggest problem I have with comments is that they quickly fall out of sync with the code. The code gets updated but the comments stay the same. Now you have a situation worse than no comments: misleading comments. It sometimes happens with self-documenting code too, but only when someone refactors enough of the code so that the class or method no longer matches the original name.
I hear this all the time as to why comments are "bad" (and I'm not suggesting that's what _you_ are saying, btw). Comments need to be kept up-to-date with code changes. The same way unit tests are kept up-to-date, and everything else around your code is. Comments are no exception.
Re: “My Code is Self-Documenting”
#6The biggest problem I have with comments is that they quickly fall out of sync with the code. The code gets updated but the comments stay the same. Now you have a situation worse than no comments: misleading comments. It sometimes happens with self-documenting code too, but only when someone refactors enough of the code so that the class or method no longer matches the original name.
This is a reason to check comments in code reviews not to avoid comments completely.
Re: “My Code is Self-Documenting”
#7The biggest problem I have with comments is that they quickly fall out of sync with the code. The code gets updated but the comments stay the same. Now you have a situation worse than no comments: misleading comments. It sometimes happens with self-documenting code too, but only when someone refactors enough of the code so that the class or method no longer matches the original name.
I hear this all the time as to why comments are "bad" (and I'm not suggesting that's what _you_ are saying, btw). Comments need to be kept up-to-date with code changes. The same way unit tests are kept up-to-date, and everything else around your code is. Comments are no exception.
>Comments are no exception.
but they usually are.
Re: “My Code is Self-Documenting”
#8I treat the comments in my code as notes... things future developers will need to know, TODO's, occasionally why I'm doing things a certain way, or other things that may be forgotten. I try to make the code as readable as possible so comments aren't needed. If you really want the documentation, look at the tests. My test descriptions describe what the code should be doing. The actual tests describe the API. Then there's actual documentation. This tends to cover more high level stuff. If the code provides an API others will be using then I'll provide documentation on how to consume it, otherwise my tests describe the API.
All of that being said, I'm not dogmatic about any of the above. I'd prefer my code to be self-documenting, but I understand it isn't always for any number of reasons.
Re: “My Code is Self-Documenting”
#9The biggest problem I have with comments is that they quickly fall out of sync with the code. The code gets updated but the comments stay the same. Now you have a situation worse than no comments: misleading comments. It sometimes happens with self-documenting code too, but only when someone refactors enough of the code so that the class or method no longer matches the original name.
The danger of stale comments is, I feel, overblown.
First, other developers know that comments can grow stale, so they're unlikely to treat them as sacrosanct, although I admit to falling into that trap.
More importantly, most of the types of comments that Eric recommends can drift out of sync with the code and still be useful. Why is this code here? What happened previously that is no longer in the code? What tradeoffs have been chosen?
Re: “My Code is Self-Documenting”
#10Earlier quoted context omitted.
I hear this all the time as to why comments are "bad" (and I'm not suggesting that's what _you_ are saying, btw). Comments need to be kept up-to-date with code changes. The same way unit tests are kept up-to-date, and everything else around your code is. Comments are no exception.
>Comments are no exception. but they usually are.
Well this seems like a problem with code reviews (or lack of), rather than with the comments themselves.