Skip to Main Content
Prefactoring
book

Prefactoring

by Ken Pugh
September 2005
Intermediate to advanced content levelIntermediate to advanced
240 pages
6h 28m
English
O'Reilly Media, Inc.
Content preview from 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 ...

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.
Start your free trial

You might also like

Understanding Unittest.Mock

Understanding Unittest.Mock

Mario Corchero
Java™ Performance

Java™ Performance

Charlie Hunt, Binu John

Publisher Resources

ISBN: 0596008740Supplemental ContentCatalog PageErrata