Undocumented Tricky Code

"Comments are annoying!"

So is maintaining UndocumentedTrickyCode. Which one costs more money? [hint: Maintaining code can cost upto 100 times as much as the initial development; cf. CodeComplete by SteveMcConnell]. (From MeaningfulComments.)

Replace UndocumentedTrickyCode with Clear Code. Don't document it, rewrite it. Documented Tricky Code is still Tricky Code. It is still likely to contain errors, likely to be hard to maintain, likely to confuse the passers-by and speed up the Warm Heat Death of the Universe. Just say no.

It is possible that some code, even after being made clear, will need comments. It could happen. Comments, however, are a very poor second to Clear Code. Don't give up.

---

On how to rewrite tricky code:

1. Write UnitTests for the tricky code.
2. Write code that is understandable and that passes the tests.

---

Ahh, yes. The ever-present, never-ending discussion of "tricky" code that needs documenting to back it up. Welcome to the real world, folks. In the area of EmbeddedSystems we need to drive hardware, usually with some real time considerations. Often the hardware needs to be tickled just right to make it perform optimally. Many, many times I have seen -- and have created -- code that provided just exactly what the real world needed to get things swingin'. I always created some description in the source and complementary design notes to explain what I was doing. Any time I have found snippets like this that weren't properly documented in somebody else's source I added comments to the code and usually some design notes to go along with them.

So it has been, and so it shall be, forever. Amen.

-- MartySchrader

---

CategoryDocumentation