The Hell of Non-Self-Documenting Code

There were a lot of buzz about self-documenting code a while ago, and there will probably be much more. I'm not that big fan of it (neither am I a fan of anything but music), but it is really helpful sometimes.

Do you hate lack of documentation as much as I do?

Plenty of languages are more self-documenting than they seem to be. On the other side, the thing that seem self-documenting, aren't always like that.

Take php. Imagine there's a torrent tracker software written in php:


function announce($passkey, $info_hash) {
//plenty of code here
    return bEncode($resp);
}

Pretty obvious, isn't it. Sure. But.

But what?

It is so obvious only if you use some framework to route HTTP requests to your classes and methods. It that case yes, any (awaited) GET parameter has a corresponding function argument, and you can easily see what is passed to /announce.

But what if the application is built like “old-style”: one atomic action – one file? I have to admit, that this style has it's advantages, among some weaknesses.

The worst thing about it is that you have to document it. If you don't – you forget what should be submitted to this particular script. Or, if you remember, a serial killer who reads your code, doesn't know what input does this piece of code wait for.

Use MVC frameworks if you are too lazy to write comments. Please!

Oct. 06, 2007 // 05:17 | Comments (0)