Un-comment your code

Saturday 28 May 2011, 14:58:00 | software dev

Hoezo "schrijf commentaar in je source code!"??

Het probleem is dat code vaak verandert, en het updaten van commentaar gebeurt niet altijd. Tevens is het idee niet "je moet commentaar schrijven!" maar "je moet duidelijke code schrijven die mensen snappen!". Als dat kan zonder commentaar, doe dat dan.

Zie ook: Uncomment your code (slideshow door Miki Tebeka)

We take shortcuts and write comments (which is easy)

to explain obscure code instead of writing clear code (which is hard)

Problem is: code always gets updated, but comments only sometimes

So we get obscure code with outdated comments. Not the place we want to be.

En een fragment uit een recente thread op comp.lang.python:

Richard Parker:

My experience is that comments in Python are of relatively low usefulness. (For avoidance of doubt: not *zero* usefulness, merely low.)

Grant Edwards:

I've seen plenty of comments who's usefulness was not zero. It was less than zero.

Ikzelf:

Someone once taught me, "There is one thing worse than having no comments in the source code: having incorrect (or 'lying') comments in the code."

Grant, I guess you hint at such comments?

Grant Edwards:

Yes. :-)

When trying to find a bug in code written by somebody else, I often first go through and delete all of the comments so as not to be mislead.

The comments reflect what the author thought the code did at some point in the past. What matters is what the code actually does at the present.

People have replied:

Rik vd Ende

2011-05-30 13:08:00

Ha ha. Bij mijn vorige werkgever waren comments alleen toegestaan in standaard libraries, nooit in maatwerk.

Hier hebben we ooit iemand gehad die een heel stream-of-consciousness dagboek bijhield in haar code comments. Ze had er ook een handje van om wijzigingen aan 'haar' code altijd terug te draaien in CVS, maar dat is een ander verhaal.

/** This method returns the relationId as a String. */ public String getRelationId() { return relationId; }

Irmen de Jong

2011-06-08 03:13:00

Code comments als een dagboek, geweldig :-)