What should we do? Well, our first reaction is to put some comments in the code. A big block comment listing the six or seven or eight items it takes to do the job might help. Except that I keep forgetting two of the steps, and I wrote this stuff. We might write it up and hand everyone who has to maintain this code a copy of this chapter of the book, or even a special document, Instructions for Adding a New Inserted Tag. Thats what we might do, and its what many wise people might tell us to do. But thats not what were going to do: were going to fix it.
The need for comments, and the need for documents, is the codes way of telling us that it isnt finished, that it isnt simple enough. Were going to make it simple, and two things are going to happen. First, I bet that it wont take any longer than writing the document we think we need. Second, it will make our own job easier as well as that of the programmer who comes after us. Third, its going to be a lot more fun than writing a document. Fourth, well feel proud of what we have done, instead of vaguely ashamed. Wow, four things instead of just two. Were exceeding expectations already. Lets plan.