I believe there’s no such thing as ‘self documenting code’, for several reasons.

I will name one: The code can only tell you what it is doing. Not what should have been done. That means that if the code has a bug, there’s no way you are going to find it by reading it!

Let’s take a trivial example:

for (i = lstItems.count; i >=0; i–) { .. }

Well, is this code right? Wrong? Who knows… There’s no programmer, in his right mind, that will dare to touch this code if it was already in production. S/he may suspect this code is ‘broken’ but s/he cannot know for sure, so it will stay that way until it crushes (or forever).

Now say there was this line of documentation before the code:

// Loop over the Items list backwards.

So, is the code buggy? Sure it is!

And this is for a very trivial example. Once you get into more complicated scenarios, comments become all the more important.

Karl Reitschuster

Okay, there are definitely some very small program units that don’t need any explanation, but….

Often I discover some hellish program unit (read: large), that looks beautiful, but no comments. Questions like where did the original coder intend the routine to be called from, what business requirements was it trying to hit, what are the preconditions and postconditions on the unit running, are there any hacks in the code to get around bugs or unusual situations, if a workaround for a database issue — what version of the database did the bug occur in ….. and so on.

“Just” readable code without any comments just doesn’t convey this sort of information.

The fact of the matter is most developers don’t like writing documentation, they’re too lazy, and this is another reason developers as a group get a bad wrap.

I think a lot of developers who took the whole readable code band wagon on board, took it outside of the context that you need to comment when commenting is necessary. They are both useful techniques.

Phew! So much pent up rage for a Saturday morning

Cheers,

CM.