The traditional approach to capturing design work is to write up the designs in a
1563
formal design document. However, there are numerous alternative ways to
1564
capture designs that can work well on small projects, informal projects, or
1565
projects that are otherwise looking for a lightweight way to capture a design:
1566
Insert design documentation into the code itself
1567
Document key design decisions in code comments, typically in the file or class
1568
header. When you couple this approach with a documentation extractor like
1569
JavaDoc, this assures that design documentation will readily available to a
1570
programmer working on a section of code, and it maximizes the chance that
1571
programmers will keep the design documentation reasonably up to date.
1572
Capture design discussions and decisions on a Wiki
1573
Have your design discussions in writing, on a project wiki. This will capture
1574
your design discussions and decision automatically, albeit with the extra
1575
overhead of typing rather than talking. You can also use the Wiki to capture
1576
digital pictures to supplement the text discussion. This technique is especially
1577
useful if your development team is geographically distributed.
1578
Write email summaries
1579
After a design discussion, adopt the practice of designating someone to write a
1580
summary of the discussion—especially what was decided—and send it to the
1581
project team. Archive a copy of the email in the project’s public email folder.
1582
Use a digital camera
1583
One common barrier to documenting designs is the tedium of creating design
1584
drawings in some popular drawing tools. But the documentation choices are not
1585
limited to the two options of “capturing the design in a nicely formatted, formal
1586
notation” vs. “no design documentation at all.”
1587
Taking pictures of whiteboard drawings with a digital camera and then
1588
embedding those pictures into traditional documents can be a low-effort way to
1589
get 80 percent of the benefit of saving design drawings by doing about 0.20
1590
percent of the work required if you use a drawing tool.
1591
Save design flipcharts
1592
There’s no law that says your design documentation has to fit on standard letter-
1593
size paper. If you make your design drawings on large flipchart paper, you can
1594
simply archive the flipcharts in a convenient location—or better yet, post them
1595
on the walls around the project area so that people can easily refer to them and
1596
update them when needed.
1597
Use CRC cards
1598
Another low-tech alternative for documenting designs is to use index cards. On
1599
each card, designers write a class name, responsibilities of the class, and
1600
collaborators (other classes that cooperate with the class). A design group then
1601
works with the cards until they’re satisfied that they’ve created a good design. At
1602
that point, you can simply save the cards for future reference. Index cards are
1603
cheap, unintimidating, and portable, and they encourage group interaction (Beck
1604
1991).
1605
Create UML diagrams at appropriate levels of detail
1606
One popular technique for diagramming designs is called UML (Unified
1607
Modeling Language), which is defined by the Object Management Group
1608
(Fowler 2004). Figure 5-6 earlier in this chapter was one example of a UML
1609
class diagram. UML provides a rich set of formalized representations for design
1610
entities and relationships. You can use informal versions of UML to explore and
1611
discuss design approaches. Start with minimal sketches and add detail only after
1612
you’ve zeroed in on a final design solution. Because UML is standardized, it
1613
supports common understanding in communicating design ideas, and it can
1614
accelerate the process of considering design alternatives when working in a
1615
group.
1616
These techniques can work in various combinations, so feel free to mix and
1617
match these approaches on a project-by-project basis or even within different
1618
areas of a single project.
1619
5.5 Comments on Popular Methodologies
1620
The history of design in software has been marked by fanatic advocates of wildly
1621
conflicting design approaches. When I published the first edition of Code 1622
Complete in the early 1990s, design zealots were advocating dotting every 1623
design i and crossing every design t before beginning coding. That 1624
recommendation didn’t make any sense.
1625
As I write this edition in the mid-2000s, some software swamis are arguing for
1626
not doing any design at all. “Big Design Up Front is BDUF,” they say. “BDUF is 1627
bad. You’re better off not doing any design before you begin coding!”
1628
In 10 years the pendulum has swung from “design everything” to “design
1629
nothing.” But the alternative to BDUF isn’t no design up front, it’s a Little
1630
Design Up Front (LDUF) or Enough Design Up Front—ENUF. 1631
How do you tell how much is enough? That’s a judgment call, and no one can
1632
make that call perfectly. But while you can’t know the exact right amount of
1633
design with any confidence, there are two amounts of design that are guaranteed
1634
to be wrong every time: designing every last detail and not designing anything at
1635
all. The two positions advocated by extremists on both ends of the scale turn out
1636
to be the only two positions that are always wrong!
1637
As P.J. Plauger says, “The more dogmatic you are about applying a design
1638
method, the fewer real-life problems you are going to solve” (Plauger 1993).
1639
Treat design as a wicked, sloppy, heuristic process. Don’t settle for the first
1640
design that occurs to you. Collaborate. Strive for simplicity. Prototype when you
1641
need to. Iterate, iterate, and iterate again. You’ll be happy with your designs.
1642
Additional Resources
1643
Software design is a rich field with abundant resources. The challenge is
1644
identifying which resources will be most useful. Here are some suggestions.
1645