3.8. Documentation of Assumptions and Decisions

 <  Day Day Up  >  

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 the documented assumption and see whether it still holds true. If a multi-CD album was always rented as a whole package, the single-ID assumption can still be true. If the album were rented as individual CDs, now the assumption is false, and the design will need to undergo modification.

DOCUMENT YOUR ASSUMPTIONS AND YOUR DECISIONS

Keep a journal for retrospectives.


 <  Day Day Up  >  


Prefactoring
Prefactoring: Extreme Abstraction, Extreme Separation, Extreme Readability
ISBN: 0596008740
EAN: 2147483647
Year: 2005
Pages: 175
Authors: Ken Pugh

flylib.com © 2008-2017.
If you may any questions please contact us: flylib@qtcs.net