practice
Doi: 10.1145/1787234.1787250
Article development led by
queue.acm.org
Could ubiquitous hand-drawn code map
diagrams become a thing of the past?
By RoBeRT DeLine, Gina VenoLia, anD kaeL RoWan
Software
Development
with code
maps
soFt WARe deVeLopeRs ReguLARLy draw diagrams of their
systems. To get a sense of how diagramming fits into
a developer’s daily work, consider this fictitious, but
representative story:
Jane is a developer who has been a member of her team
so long that everyone calls her the team historian. Since
the product just shipped a few weeks ago, Jane is finally
getting around to some code cleanup she had planned
for ages—namely, dropping a dependency on a library
that is no longer supported. Jane uses her development
environment to search for all the places where her
product uses the unsupported library. She clicks through
the results one by one and reads the code to understand
how it uses the library. As she jumps around the code
base, she sketches a class diagram on a notepad to
capture the architectural dependencies she discovers.
Partway through this code-under-standing task, there’s a knock at the
door. It’s Joe, the newest member of the
team. He is working on a bug and is confused about how one of the product’s features is implemented. As the team historian, Jane is accustomed to this type of
question. They start the conversation
by looking at an architectural diagram
tacked to the wall near Jane’s computer.
To get into specifics, Jane draws a version of the diagram on the whiteboard,
sketching only the relevant parts of the
architecture but in more detail than
the printed diagram. As she talks Joe
through a use case, she overlays the diagram with arrows to show how different
parts of the system interact. From time
to time, she brings up relevant code in
her development environment to relate
the diagram back to the code.
After several minutes, Joe feels confident he understands the design and
heads back to his office. Jane goes back
to her own work. Between exploring the
search results and answering Joe’s questions, Jane’s development environment
now has dozens of open documents.
Jane tries to resume her task but cannot
find where she left off in all the clutter.
She closes all open documents, reissues
her original search, finds her place in
the search results, and carries on exploring the dependency on the unsupported library.
This story illustrates the wide range
of diagramming practice. The diagrams range in quality from sketches
to high-quality posters; in formality,
from idiosyncratic scribbles to well-defined notations; in longevity, from
the duration of a single task to an
entire release cycle; and in audience,
from solo use, to anchoring a conversation, to communicating with the
whole team or user community.
Although the practice illustrated
in the story is widespread and useful,
there are a few downsides where software could make an improvement.
First, the diagrams are typically not
tied to the code. To go from architec-ture-level to code-level discussions requires switching tools—for example,
