Prefactoring

3.8. Documentation of Assumptions and Decisions

Keeping a journal is one way to learn from experience. In the journal, you can document the assumptions you made (e.g., the network is reliable) and the reasoning behind your design decisions. The journal can be separate from or part of the code source.

When you are faced with a design decision, you must have at least two alternatives. If you have only one option, you really have no decision to make. You might employ one of the guidelines in this book to aid you in your decision making. As you make decisions, document why you made them, especially for the more important ones. Later on, you can analyze those decisions and examine how your reasoning and assumptions worked out.^[*]

^[*] You can use the journal in the retrospectives discussed in Chapter 1. See also "Design decisions" at http://www.agilemodeling.com/essays/agileDocumentation.htm.

The requirements outline what functionality your system needs to provide. The code itself says how you are technically providing that functionality. However, the code does not document why you chose that particular technical approach. The journal provides the "why." For example:

"Sam stated that he never buys any CDRelease that has more than one physical CD. Therefore, there is only one physical CD that corresponds to a CDDisc and therefore only one ID associated with each CDDisc."

Suppose that later on, someone brings up the issue of CDReleases that contain more than one physical CD. You can examine ...