Prefer Tests Over Comments

James Mead — Thu, 10 May 2007 15:29:00 +0000

One small a-ha moment in my early programming days was when someone suggested it was better to write a comment explaining why a chunk of code worked the way it did, rather than simply describing how it worked – essentially a direct translation of the code into english sentences.

Since then I’ve become a test-infected, test-driven developer and now I would always choose to write a test in preference to writing a comment. But I think the same lesson still applies…

I’ve recently been making a conscious effort to come up with better test names. The easy option is for the test name to reflect what happens in the test. But it makes the test much more valuable if you can use the test name to explain why the behaviour is the way it is.

Comments are also often used as to-do items, but I think tests can be a better solution. For example, Ben mentions leaving notes for the team in tests.

"Prefer Tests Over Comments" by John

Fri, 11 May 2007 10:16:04 +0000

Bravo! It is always better to leave the explanation of your code in a location way out of the way. I mean, having it right above the method would just clutter the mind-boggling beauty that is the sacred code.

Also, why allow non-initiates to read your code’s comments to make sense of what it is doing. If someone wants to know what it is doing, well they better be ready to learn that JOY that is the language the YOU chose to develop in.

I got two words for you: Knuth+Literate Programming (okay maybe three words)

but you see, you are smarter than Knuth, because you follow the latest FAD, while he is just some old fart who talks about like stuff which is like hard and stuff.

Floehopper: Prefer Tests Over Comments

Prefer Tests Over Comments

"Prefer Tests Over Comments" by John