Thinking inside a bigger box - Latest Comments in If You Can't Say Anthing Useful...

Re: If You Can't Say Anthing Useful...

Marius Mårnes Mathiesen — Wed, 15 Mar 2006 12:24:48 -0000

I just stumbled across another piece of fantastic code comments that I'd love to share. It's from the PHPUnit2 documentation, have a laugh:

protected function setUp()
{
// Create the Array fixture.
$this->fixture = Array();
}

public function testNewArrayIsEmpty() {
// Assert that the size of the Array fixture is 0.
$this->assertEquals(0, sizeof($this->fixture));
}

public function testArrayContainsAnElement() {
// Add an element to the Array fixture.
$this->fixture[] = 'Element';

// Assert that the size of the Array fixture is 1.
$this->assertEquals(1, sizeof($this->fixture));
}

Re: If You Can't Say Anthing Useful...

Kjetil — Fri, 24 Feb 2006 21:24:44 -0000

Too shy: just enable automatic code folding for comments in IntelliJ. Then you can unfold if you need a close look.

Re: If You Can't Say Anthing Useful...

Ole Christian Rynning — Wed, 22 Feb 2006 02:48:59 -0000

For object oriented languages I feel the class header should ALWAYS be commente.

_Especially if the classname is a generic one like *HashTable_.

One of many nuiances working with legacy code is figuring out in which context(s) classes are used and sometimes the mere purpose of them without reading through the entire class.

If you call outside objects methods its useful to briefly tag them with a comment or even a @see doclet.

Re: If You Can't Say Anthing Useful...

Too shy to say my name. — Mon, 20 Feb 2006 19:26:28 -0000

Obvious comments do suck when you look at the code. However, sometimes (like just before negotiating your salary or vacation plans - or for some other personal or professional reason) you might want to use the javadoc tool to generate fancy and goodlooking API documents to show someone to prove, or create the illusion of, work well done! In this case the tagline "Never, ever, say in comments what the code already says." is not appliable as there is no code to look at, but only the generated API docs! I still agree that comments should not be verbose, but they should be there (even if they are slightly useless and redundant when you have the souce code in front of you). Keep them in dense form though.

P.S. Wouldn't it be nice with a "do not show comments"-function in the IDE? Then we could have both clean code and nice API docs at the same time with no annoyance.

P.S.S. Almost forgot; writing good code is just as hard as writing good comments. Some programmers are actually better at writing comments than code and in those cases having comments to read before rewriting their uncomprehensible code is nice.