If you know me, or maybe you can just tell from my blog, I can be verbose.

It’s how I am. I tend to prefer more information to less. I think you get further in life by knowing more, not less.

But I also know this wears on a lot of people. They just want the bottom line and don’t care why or how you got there. IMHO that’s a pity because then they never truly understand and can never arrive at educated conclusions on their own. OK fine, a baby is made, that’s the bottom line. If you want to stop there and never know more, that’s your business. But in my book, knowing how to make that baby is interesting, and then going through the motions of making that baby even more interesting. 🙂  Like I said, it’s good to have knowledge and information.

I write software for a living. There’s great debate about documenting code, be it formalized documentation apart from the code or writing comments in the code itself. I’ve never jived with folks that say code should be self-documenting and that’s all the documentation you need. Sure, you should write readable and maintainable code. Naming your variable “numberOfObjects” is far better than just naming the variable “i”. But you must have comments. Why? Precisely.

Self-documenting code can tell you what and how, but it cannot tell you why. For that, you must use external documentation.

You must go through the effort of writing comments to explain bits of code. Depending on the code, you may also want to write larger external documents (e.g. in a word-processor) that explain the greater architecture and how all the parts of the code fit together and how to use it all. This is something that cannot be conveyed by reading the code itself, and I just don’t understand those that think this sort of documentation is a waste of time and somehow if you do it makes you “not a real programmer”.

Well buddy, real programmers know the moment after the code is written it must start being maintained. If you can’t remember what you had for breakfast a week ago, can you expect to remember why you wrote this code when you come back to it in 6 months?

Case in point. Just yesterday I was working on a bug in our software where the application would hang. All signs and symptoms were odd but somehow made sense to each other. When our QA guy told me one key point (“looking at the permissions flags, there’s a ‘p’… what’s that?”) it all came back to me. The file was a named pipe and I dealt with this very problem in the past. I went looking in code for where I previously dealt with it. I found it. The comment was dated over 5 years ago.

5 years ago.

When I fixed the problem — 5 years ago — I added copious comments to the source code to explain the problem in great detail; 50 lines of comments. I know many would say that was ridiculous! That it’s just his (annoying) verbosity! Well, thank goodness for it because without it there would have been no way I would have remembered that 5-year-old problem in such great detail and know exactly how to fix it (again) today.

Here’s an article by Jef Raskin discussing the same thing. Jef Raskin would know.

So yeah… people tell me I’m verbose. I really don’t care. I am who I am and I know when to be curt and I know when to ramble on. There are times when comments aren’t needed (don’t tell me what or how), but you do need to explain why and not be afraid to go into detail because the code you may have to maintain may be your own. Do yourself a favor and explain yourself. And if someday that code gets to be maintained by someone else, do them a favor and explain yourself.

I’ve never known anyone to say there’s such a thing has having too little ammo. I feel the same way about code comments and information. 🙂