Comments on: If You Can’t Say Anthing Useful…

By: Marius Mårnes Mathiesen

Marius Mårnes Mathiesen — Wed, 15 Mar 2006 17: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));
}

By: Marius Mårnes Mathiesen

Marius Mårnes Mathiesen — Wed, 15 Mar 2006 14: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));
}

By: Kjetil

Kjetil — Sat, 25 Feb 2006 02:24:44 +0000

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

By: Kjetil

Kjetil — Fri, 24 Feb 2006 23:24:44 +0000

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

By: Ole Christian Rynning

Ole Christian Rynning — Wed, 22 Feb 2006 07: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.

By: Ole Christian Rynning

Ole Christian Rynning — Wed, 22 Feb 2006 04: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.

By: Too shy to say my name.

Too shy to say my name. — Tue, 21 Feb 2006 00: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.

By: Too shy to say my name.

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

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.