Code Comments, Documentation
Writing code tends to be harder than it needs to, because there’s a constant need to please a bunch of other people who want to read and understand it. Sometimes, the person who writes the code needs to worry about being able to understand it several months later.
Conventional wisdom holds that the solution to the problem is documenting the code appropriately. Conventional wisdom is wrong. Reasons are manifold, and quite obvious once you start to think about it.
Documentation is always out-of-date. It’s impossible to have anyone and everyone who updates code to update the comments and documentation accurately. Sure, you could try, but to a large extent, this is simply beyond your control. Typically, this means you need to assume the documentation is wrong and read the code in detail anyway, so you might as well simply start by reading the code.
Reading the code is the only way to figure out what it is doing. Documentation only tells you what somebody thinks the code is doing. It is quite possible that they’re wrong, or only partially correct. Besides, it’s better to build up a model of what you think the code is supposed to do, than to be told what to expect.
Code is more concise. If the code is well-written and self-documented, it is generally faster to read the code and understand what’s going on than to read the comments (which are, by definition, more verbose than the code they attempt to explain). And if you can’t trust the programmer to write good code, you can’t trust the guy to write good documentation either.
There are some situations where documentation is necessary, of course. Examples would be when you are attempting to explain the motivations or structure of your design at a larger scale, or if you want to explain what the code is not — why you decided to something one way and not the other.
Tags: Code, Documentation
December 8th, 2009 at 13:01
aha, ext4 inspired anyhow?
December 8th, 2009 at 22:16
I guess a big problem with documentation is that it tries to explain the working of something that is very objective in nature. I mean, to the programmer, it will be too obvious to be explained and to the third person, it’ll be too complex to understand anyway. That’s why I always thought that documentation, beyond a very brief summary of the line of thought of the programmer, is useless. But then, I doubt geeks ever understood the need for such things anyway
.
December 8th, 2009 at 22:29
No, Slashdot-inspired…
December 8th, 2009 at 22:42
@Chintan: I suppose there are levels of geekiness.
Long time no see, how have you been?