News for hackers. Stuff that matters.
Re:Doom 3 Source code review by Muzza on Saturday June 09, 2012 @03:34AM (#4087531)
>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.

Re:Doom 3 Source code review by forrestthewoods on Saturday June 09, 2012 @05:30AM (#4087711)
Bad comments are bad comments. Read the code/comments actually being referenced and it's clearly of high quality.
Re:Doom 3 Source code review by mappu on Saturday June 09, 2012 @03:58AM (#4087567)
At 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

Re:Doom 3 Source code review by DeepDuh on Saturday June 09, 2012 @04:23AM (#4087596)
That's really a fun example. It took me a while to even find the definition of f after having been distracted by all the comment clutter. Point taken.
Re:Doom 3 Source code review by gjm11 on Saturday June 09, 2012 @06:55AM (#4087819)
The actual algorithm is rather nice, despite the reader-hostile presentation...
Re:Doom 3 Source code review by regularfry on Saturday June 09, 2012 @09:42AM (#4088070)
> Please don't write out what the programming language constructs do in English.

Exactly this. Comment the why, not the what.

Re:Doom 3 Source code review by alan_cx on Saturday June 09, 2012 @07:33AM (#4087855)
I 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.

Re:Doom 3 Source code review by Havoc on Saturday June 09, 2012 @09:52AM (#4088093)
Depends on the code imo. If its vicious 3D code that is fully of tricky optimization then a pile of comments is perfect.
Re:Doom 3 Source code review by FuzzyDunlop on Saturday June 09, 2012 @07:23PM (#4089658)
Though 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.

Re:Doom 3 Source code review by phaemon on Saturday June 09, 2012 @08:55PM (#4089825)
// 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.

Re:Doom 3 Source code review by jakejake on Saturday June 09, 2012 @06:01PM (#4089451)
Unfortunately 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.

Re:Doom 3 Source code review by thenonsequitur on Sunday June 17, 2012 @10:31PM (#4124632)
I 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...
Re:Doom 3 Source code review by batista on Saturday June 09, 2012 @04:18AM (#4087590)
>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?

Re:Doom 3 Source code review by Muzza on Saturday June 09, 2012 @04:25AM (#4087598)
Throwing the baby out with the bath water. I'd much rather have good comments.
Re:Doom 3 Source code review by Confusion on Saturday June 09, 2012 @06:08AM (#4087762)
The 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.
Re:Doom 3 Source code review by Retric on Saturday June 09, 2012 @09:33AM (#4088057)
Unfortunately, that tends to lead to vary stale comments which hinders the next developer.
Re:Doom 3 Source code review by Confusion on Saturday June 09, 2012 @12:00PM (#4088365)
Yes, 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.