I also disagree. Commenting is something I do when I'm being lazy - too lazy to make the intent of the code obvious. Sadly, this is also the impression I get when I see comments written by other developers. (That said, method-level documentation is still something I'm on the fence about.)
Comment your damn code
21–30 of 68 posts
Re: Comment your damn code
#22Note that the following does not count as commenting your damn code: // Get the account holder currency $currency = $accountHolder->getCurrency(); Imagine several 10s of KLOCs where 99% of the comments are as worthless as this and most people are content with their efforts because they believe they are commenting thoroughly.
People learn this bureaucratic sort of stuff in school, where they are graded in a bureaucratic fashion.
As with all things, ROI is key. Your commenting effort is a finite resource. Expend it in the way that gets you the most value.
Re: Comment your damn code
#23I prefer tests over comments.
Comments can't guarantee to represent what the codes does always. "Don't be lazy" is a fine argument, but it takes one time that you are under pressure to ship right away and you don't comment. Tests, on the other hand will keep failing until they describe the updated version of the code.
We should strive to make code obvious, when it's not obvious, then you should comment, or better: simplify your code.
Re: Comment your damn code
#24"Every 3 to 7 lines of code you'll find some amount of editorializing. Maybe every few hundred lines you'll find a good joke too."
I think there's the issue. In applications I write, every 3-7 lines of code is refactored into a method that is named exactly what it does, and every few hundred lines of code (usually much less) is in a separate file and class named on what he does. Broken out like that, there's not many places to put a comment that would be of any use.
But not broken out like that, of course you're going to need comments. But I think you'll find that comments aren't even enough.
"I know what the code says. But tell me the intent."
I think unit tests and expressive code work much better to achieve this goal.
Re: Comment your damn code
#25I used to work with someone who would start writing a function or module by writing their code as comments.
# First we iterate over the directory and get a list of files to process
...
# Then we process them
Nothing was more tedious to read. It's like having a narrator tell you exactly what each character is going to say right before they say it. It is quite maddening to this reader and I had to constantly review this sort of code.
I had to politely approach the person writing this code and explain this to them. Comments are not for describing what can already be read. One's code should be written in such a way as to inform a programmer maintaining the code to its purpose and utility. That means short, single-purpose functions, conventions, idioms, and all of that. But it also means that comments should only be used when you're going against convention or doing something hack-ish on purpose.
I saw fewer lines of comments until a fresh, new young team member joined...
Re: Comment your damn code
#26Why comments are important: they represent intention . A reasonable complex method can have a wide variety of inputs which the author can't be expected to have tested across the entire range of values. For example, if you have six boolean inputs, you have 2^6=64 possible combinations. If you have six integer inputs, you have roughly (4e9)^6=4e57 combinations, which is more than the number of atoms in the Earth. Expre…
Intention is all well and good, but imprecise. It also is not accurate to suggest that what is written is what is intended. One of the best ways I know of to describe intent is with tests. Not only do well written tests describe exactly what is being done, but it also tests to enforce this. There is no mistake about what it expected and intended.
A comment, on the other hand, cannot be trusted. Ignoring the fact that it could simply be out of date and wrong, your interpretation of intent might not the same as the person writing it. A lot of this might be because you simply don't share the same context. After all, when this comment was written has a context beyond the location of the code.
Re: Comment your damn code
#27I'm against commenting code, with two exceptions: - You're implementing something complex (like an algorithm) - You're implementing something stupid (typically a workaround for something that could not be done in a more elegant way, and you want to explain why it can't be refactored) If the code is well written it is also self explanatory. This can be done by structuring / formatting the code well, into methods, clas…
I agree, but unfortunately they're also necessary in circumstances, hopefully rare, when your ability to choose your own names is otherwise constrained for whatever reason - a configuration file, or a framework dictating conventions, for example. If you have have to do something complex, and there's absolutely, positively no way to explain it in code, then comments are appropriate. Otherwise, the impulse is misguided.
Re: Comment your damn code
#28Well, I disagree. Test-drive your damn code. The difference in positive impact will be a few orders of magnitude.
OP make a good point that comments help to make your intent more clear, while the code itself just explains what the program does. Very good reason to have some comments here and there.
But I'm with Toshiro - test your damn code! Testing first brings all the benefits of commenting and more:
Tests help document and clarify your intent. They convey your assumptions, expectations, and show you exactly how methods are expected to behave when you run the test.
3 months later when you're adding new features, a failing test tells you that you introduced a bug before you ever run the new code.
That said, comments have a place in the tests themselves. Much better than scattering comments all around the code base.
The other place for comments is in the version control. Make small, frequent commits and set up your version control so that it forces you to comment each time.
When you're doing these things, comments in other parts of the code are just redundant and noisy.
Re: Comment your damn code
#29Note that the following does not count as commenting your damn code: // Get the account holder currency $currency = $accountHolder->getCurrency(); Imagine several 10s of KLOCs where 99% of the comments are as worthless as this and most people are content with their efforts because they believe they are commenting thoroughly.
Those aren't comments, that's someone being lazy. A comment should describe the why or the goal, not the how.
Personally I appreciate good "how" comments for algorithm implementations in C++, where the implementation in code isn't as clear as a (perhaps less efficient) pseudo-code version in the comments. "How" comments are just as valid as "why" comments, and the parent comment illustrates that "copy-comments giving no more information or intuition than the code" are worthless, which is why I don't have comments every 3-7 (not even every 20) lines like the submission suggests.
Re: Comment your damn code
#30I'm against commenting code, with two exceptions: - You're implementing something complex (like an algorithm) - You're implementing something stupid (typically a workaround for something that could not be done in a more elegant way, and you want to explain why it can't be refactored) If the code is well written it is also self explanatory. This can be done by structuring / formatting the code well, into methods, clas…
Agree completely
C# 11 years of experience