Docs, fast and slow

I used to have so much pride in not having documentation. Just look at the code, I would say. It’s short enough. And it was, being scripts and all – but what do I think as I wade through namespace classes, gazing blearily at peeked file after file? I wish there were documentation: someone to hand-hold me through all of this, a pretty-print manual with a nice font, a guide – something to bookmark, like hidden gems in MSDN. I guess if you need it, write it.

Writing pseudocode after the fact is like chewing your food. The eyes skip everything. Typing the explanation gives time to digest. There is design up-front, which everyone knows and few do. Documenting legacy code forces me to think clearly. Maybe outlines are useful solely to constrain a storm into lines. Some system of organization after the draft helps.

I have not written serious code in a while. Any period of longer than a week for a working programmer is an eternity. I’m close to grabbing RATFOR or starting C. Anything to be wrestling with off-by-ones, mentally turning sludge into beliefs – surety in subtraction, knowing how the loop terminates.

Advertisements