Every non-trivial piece of software represents one leaf of a large decision tree.  The nodes in the tree represent tradeoffs: speed versus space, generality versus efficiency, choice of platform, choice of algorithm...  Some  decisions are trivial; others are profound, and constrain the software's future in ways never expected by the designer.  Some decisions have nothing to do with software constraints at all, but are responses to organizational politics or the developer's ignorance.

If I write a perfectly lucid system, one which makes it trivial for the reader to answer any question about "How does this work", I have explained what the leaf does.  I have not explained why the system wound up at this leaf rather than any of its neighbors.  Without the why, the next developer is handicapped in reexamining my decisions; he knows that I used QuickSort, because it's staring him in the face, but not why I thought Quicksort was the best solution to the problem.  If I had exposed my intentions, the next designer could reevaluate my decisions and see whether they were still valid according to the constraints he confronts.

Therefore:  Document Your Intentions.  When you make a major design decision, leave some record behind.  The record could be a design document, a block comment in the code, or a note in the project notebook.  Whatever form the record takes, it describes what constraints you saw, and why your solution seemed the best response to those constraints.   Those who must extend your work will be very grateful you took the time.

-- BetsyHanesPerry
----
CategoryMaintenance