For the love of all that is good and kind ....

[rgrzywinski]

PLEASE document commented out blocks of code.

How may times have we all commented out of block of code for testing only to check in the code that way?  Now someone else (or even you, some time later) comes through and sees the commented out block.  Was it commented out for a bug?  It is to-be-added-later functionality?  Was it an accident?  Who knows!

Well, this can be easily mitigated if you always document the block the moment that you comment it out.

Some examples:

// NOTE:  commented out for testing.  Uncomment!
//    if(here == there) {
//        doStuff();
//    } /* else -- here is not equal to there */

...

// NOTE:  this is currently causing a bug
//    for(int i=0; i<n; i++)
//        i = n;

...

// NOTE:  this is unused at the moment but is valid / correct code
//    getFoo(bar);
//    bar++;

Oh why oh why do we continually screw ourselves and other by thinking that in-code documentation (i.e. comments) is optional?

[cfmdobbie]

Because Sun has set an incredibly bad example the whole area of comments in source code.  I'm currently banging my head against a wall trying to get JMF to work, and because there is NO documentation of note (apart from several-versions-old JavaDoc) I'm digging through the source.  Here's one gem:

// TEMPORARILY COMMENTED OUT URLDataSource: 1/15/99
// 	if( source == null) {
// 	    try {
// 		source = new URLDataSource(sourceLocator.getURL());
// 		source.connect();
// 	    } catch(MalformedURLException me) {
// 		// Can't get a URL so we're done.
// 		source = null;
// 	    }
// 	}

Temporarily?  This was five and a half years ago... :roll:

[princec]

Sorry We'll try to be a bit more considerate with our commenting out.

Cas

[rgrzywinski]

Thanks Cas.  Sorry for the rant.  I get very angry when I attempt to contribute to OSS projects and something that should take 30 seconds takes hours due to the fact that programmers are under the impression that comments are optional.  Given the intrinsicly distributed nature of OSS code, comments are more important than in non-OSS code (not to imply that non-OSS code is typically commented or that comments are not important).

And cfmdobbie, I feel your pain.  The Java source is soooo bad that I'm amazed that it works and scared to use it.  I was praying that they'd have a 2.0 where all that was done was a good house cleaning (to remove things like Enumeration so that half of the code doesn't return Iterator and the other half return Enumeration).  Given that they've spring-boarded over 2.0, 3.0 and 4.0, I doubt this will ever happen  :shock: