12-20-07 - 1

More and more programmers are becoming responsible about documenting the code, describing what it does, what you need to pass in. That's all well and good, but it's still missing a huge aspect - documenting what's NOT in the code.

Code that just does something really has very little value. If you know what the code should do, it's easy to write. What does have a lot of value is a record of the knowledge and experimentation that went into a piece of code. If someone spends months trying all these different ideas, and finally comes up with a great solution and writes the code - the most value piece of that is all the things that were tried and ruled out. You need to write up why you are not doing the alternatives.

Often the trickiest bits of experience-based code look really trivial and don't get commented at all. Sometimes the nastiest weird case bug fixes just consist of doing a check that seems redudant. These are the things that really need to be richly commented for the future.

Without this stuff, the code picks up a lifespan where its usefulness dies as the knowledge used to make it dies.

No comments:

old rants