4 ms·
>In some part of the code (see dmap page) there are actually more comments than statements. >Dmap source code is very well commented, just look at the amount o
by Muzza 14y ago
>In some part of the code (see dmap page) there are actually more comments than statements.
>Dmap source code is very well commented, just look at the amount of green: There is more comments than code !
You know, in my experience that's not a good thing. I work on similar, heavily-commented code and find it extremely painful. At some point it becomes a burden to see the code behind the comments. (And just so no one misinterprets me: I am not against comments /per se/.)
It's like when you read code written by someone who simply loved whitespace and who appended a useless "banner comment" after each real comment[1]:
// If x is less than 3, do stuff 50 times.
// -----------------------------
if ( x < 3 )
{
// While i goes from 0 to 50.
// --------------------------
for ( int i = 0; i < 50; i++ )
{
// Do stuff.
// ---------------
doStuff ( ) ;
}
}
So what would've fitted in one screen of text, if written in a sensible fashion, now requires one and a half screen and lots of scrolling.
[1] The comments in the example are actually both crappy and pointless. Sadly, the program I work on is riddled with them. Please don't write out what the programming language constructs do in English.
- mappu 14y agoAt least in that case you can attribute it to well-intentioned stupidity. Here's my favourite short example you must instead attribute to malice: [1] a closed-form implementation of fibs(n). Follow along with the comments! 1. https://gist.github.com/eb02e9546102594e8bf7 https://gist.github.com/eb02e9546102594e8bf7
- batista 14y ago>At some point it becomes a burden to see the code behind the comments. (And just so no one misinterprets me: I am not against comments /per se/.) Then use an editor/IDE that can automatically hide or fold the comments?
- Muzza 14y agoThrowing the baby out with the bath water. I'd much rather have good comments.
- Confusion 14y agoThe problem is that comments are often only good the first few times you read them. After heavily hacking on some code for a while, you know the comments. I find the ability to fold comments very valuable.
- Retric 14y agoUnfortunately, that tends to lead to vary stale comments which hinders the next developer.
- Confusion 14y agoYes, I admit that in code reviews, staleness of comments is a thing that tender to get pointed out to me. However, I've since developed a procedure (review comments belonging to any hunk of changes) to prevent that.
- forrestthewoods 14y agoBad comments are bad comments. Read the code/comments actually being referenced and it's clearly of high quality.
- alan_cx 14y agoI was taught to write programs in "pseudo code" before actually coding. Pseudo code being "English". What your example looks like to me is psudo code turned in to comments as the real code is written in underneath. Not sure how that helps or hinders, its just an observation.
- regularfry 14y ago> Please don't write out what the programming language constructs do in English. Exactly this. Comment the why, not the what.
- Havoc 14y agoDepends on the code imo. If its vicious 3D code that is fully of tricky optimization then a pile of comments is perfect.
- jakejake 14y agoUnfortunately bad comments like this leads people into thinking that all or most comments are useless. It's true that I don't want to see a comment like "loop through this 50 times". But what may not be obvious is the purpose of the loop, the significance of the number 50. Putting in "why" can save hours. The only exception where I would want a comment that just says what a line of code is for a really complex line, like a complicated regex for example.
- thenonsequitur 14y agoI agree with the point about comments being useful for a really long complicated regex, but any really long complicated regex is a coding problem to begin with. Really, instead of comments (or in addition to comments), the regex should be broken up into logical pieces separated by white-space, just like regular code is. Jeff Atwood explains it well in this classic post: http://www.codinghorror.com/blog/2008/06/regular-expressions-now-you-have-two-problems.html http://www.codinghorror.com/blog/2008/06/regular-expressions...
- FuzzyDunlop 14y agoThough I no longer have the link handy, one of my favourite examples of this was of an OAuth2 'library' for PHP. You couldn't make out the code for the endless comments. Javadoc style comments and annotations; actual comments ... there was paragraph upon paragraph of comment for individual class properties, that you could reasonably infer from their name if it was done well. It got to the point where the comments were so lengthy and prosaic, you were deterred from reading them just by their very existence.
- phaemon 14y ago// While i goes from 0 to 50. // -------------------------- for ( int i = 0; i < 50; i++ ) Well, doStuff() only happens while i goes from 0 to 49, so maybe this comment reveals a bug.