Long Day

When I used to work, one of the little utilities we used to use was Sandcastle, a Help file builder. It automatically built Help files based on special comments in your code. In my view it was of limited use for generating Help files – the ideal Help file would be far less technical than source code comments – but one way it was invaluable was just to identify where code was undocumented.

I think it was Sandcastle which did this – we certainly used something.

I tried to install Sandcastle on my PC last week, but it refused. So, today, I went through each and every file in my project (manually) and looked through every one of them (manually) to try and find stuff that wasn’t documented.

A lot of it was pretty noncey – if you have a variable called GileName, does it really need to be documented further? So, in a very few cases, I haven’t documented things, but very much a minority. I’m kinda worried because I once worked with a guy, I reviewed his code and found parts of it were undocumented. So I pulled him up on it, and his response was, “well, it’s obvious to me what the code does. As far as I was concerned, he’d completely missed the point, which was that somebody else should be able to pick up the code and understand it. The upshot is, whenever I hear myself saying “it’s obvious”, I try to take a step back. It’s difficult on a one-man project to try to police yourself.

Anyway, the result was a long day adding various comments to the code. The language I’m using goes through a process called compilation before it becomes a proper program, and in fact the compiler (the engine which does the compiling) strips out any comments before it compiles the code. So, the executable code has not changed one iota. But it’s all about the readability. If I can pick the code up in a year, and not think “what the **** does that do?” then it is a win.