I think Jeff Atwood sums things up nicely: http://www.codinghorror.com/blog/2008/07/coding-without-comm...
Comment your damn code
11–20 of 68 posts
Re: Comment your damn code
#12Note that the following does not count as commenting your damn code:
// Get the account holder currency
$currency = $accountHolder->getCurrency();
Re: Comment your damn code
#13I'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, classes, packages - and naming these constructs in a reasonable way. Naming variables is obviously also very important - and be consistent!
In my opinion comments only clutters the code, and in most cases reduces readability. Like mentioned before you cannot always trust that the comments are up-to-date, but the code certainly will - so I believe time should be spent making the code readable instead. "Look, there is what you intend and what you write" - those should be the same, there should be no in-between.
My primary language is Java by the way (about 10 years of experience).
Re: Comment your damn code
#14I think Jeff Atwood sums things up nicely: http://www.codinghorror.com/blog/2008/07/coding-without-comm...
Except In my opinion he gets it very wrong. His comment free code doesn't include the the string "Newton-Raphson" anywhere, making it non-trivial for anyone not familiar with the code to work out what is going on.
Secondly, and more importantly, he never explains why he is using Newton-Raphson to approximate the square root. If I was handed this in some code I was to maintain I would really really like to know that.
Re: Comment your damn code
#15I've been writing code in some language or another for almost three decades. My headers, comments and READ_MEs usually end up helping me more than anyone else.
When you have multiple projects in muliple languages for tens or hundreds of clients over the years, the last thing you want to do is open a project or repository and see little or no documentation. And you don't want to have to figure out what/why the heck you did in 2007 and explain the project to coworkers.
I guarantee you that clients and coworkers will pick the worst optimal time to want revisions. And if I spend the time upfront to make it simple for a junior member of my team to take ownership of a project in the future, my life becomes better.
Re: Comment your damn code
#16Earlier quoted context omitted.
I'd really like this to be reality.. but in my world, there are too many programmers who don't write code "the right way". like > %80. For the great programmers sure ok, its obvious, but for the rest of them.. no.. you're not the coding genius you think you are.. please comment your code. Don't be tricky, clever, smart.. or self-documenting. Comment. period.
If a programmer is incapable of doing this: maybeGetFileHandle :: FilePath -> IOLikeMonad (Maybe Handle) Why do you think they are capable of doing this? foo :: FilePath -> IOLikeMonad (Maybe Handle) -- If the file is available and can be read -- return Some handle. Otherwise, return None.
A nice example which expresses the bulk of the issue: Comments are largely there to compensate for the lack of information held in the type system. Adding comments which just reiterate what is said in the function signature is redundant and not worth the time.
Of course, this doesn't apply to all comments - but specifically those insane policies where you're required to write a description of every method, argument and return type.
The more powerful the type system, the less necessary comments become. If you take a dependent type system for example, or some code contracts with explicit preconditions, you no longer need to specify the valid range of values for a given function in some silly comments which will fall on deaf ears in the majority of cases anyway. The programmer will be stopped and forced to read it, rather than waiting until runtime to discover the correct behavior, if at all.
Re: Comment your damn code
#17I'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'll second that. I think comments are extremely useful for situations where the code isn't clear enough. Comments are also useful to explain why something was done a particular way when other ways might appear to be more obvious.
i.e. // unrolled this loop because this is a time critical method and the compiler isn't currently doing that for us.
My main argument against tons of comments is that they are likely to not match up to what the code actually does. No matter how vigilant the developers are there is 0% chance that the code will be out of sync with the code and a >0% chance the comments will be out of sync. If you feel the need to write comments for a block of code see if you can find a way to make the code easier to read before you try and solve the problem with a comment.
Re: Comment your damn code
#18There's usually a large amount of comments and metadata relating to code that isn't present in the source files themselves, but in an external database:
git blame path/to/file.txt
Re: Comment your damn code
#19ok, so i wrote some code yesterday. i didn't write it expecting anyone to read it (i mean, not critically on hn), and it's not as good as i would like, but it has no comments (apart from at the top of the file explaining how to use the program).
so, people who are saying "just comment it" - what would make a big difference to this code?
Re: Comment your damn code
#20Note 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.