At some point, successful software leaves the care of its creators and ventures into the world on its own. There, it will have to be changed and understood by others. In this workshop, we will explore techniques for making software more easily understood by programmers, testers, and even end users inclined to tinker. What can we do now that will help them then?

For better or worse, those who inherit software often do not inherit design or architecture documents. Or what they get is out of date or inaccurate. Since code is less likely to get lost, we focus on code and, secondarily, on tests.

Possible topics include:

• tracing and logging
• tests as documentation
• breaking encapsulation to aid understanding
• representation of design decisions and alternatives in code
• intention-revealing error handling
• self-diagnostic code
• how to avoid leaving misleading cues in the code

Our assumptions

1. Programmers working on a legacy system will always be, to some extent, doing archaeology: understanding what was in the minds of other developers using only the artifacts left behind. They're usually hampered because the artifacts were not created to communicate to the future, because only part of what was originally created has been preserved, and because relics from different times are intermingled. Forethought, or patterns of work that take the future into account, can ease their burden.
2. We assume the only artifacts left behind are executable: code and perhaps tests. Solutions that depend on other types of documents are outside our scope.
3. Speculation is wonderful, but experience is telling. We focus on techniques that have been seen to work (or fail).

Our goals for the workshop

1. Participants will share concrete techniques and approaches that they can take back and use. Each person will write better code after the workshop.
2. We will produce a summary list of suggestions for code creators. Our goal is to surface and publicize surprising areas of agreement and disagreement, especially those that conflict with the conventional wisdom.
3. We hope some of the ideas will spark academic research.

Getting into the workshop

There is a limit of 15 participants.

Participants will be accepted based on a position paper, which should be sent to marick@visibleworkings.com by September 19, 2002. The position paper will have two parts:

Experience report. This will take one of two forms. You could write as someone who was given an old system and was pleased to find something about it that made it markedly easier to understand. Or you might write as someone who tried hard to make your code easier to understand and is now reflecting on how well you succeeded.

Position statement. You will state something the world needs to know: a theory of how people understand systems, a tool you wish you had, a method to follow.

Position papers will be posted on this web site after participants are selected.

Position papers should be no more than three pages long. Shorter is fine. We prefer HTML. PDF or some format that can easily be converted into PDF is fine, too.

You'll be notified of acceptance by October 3. Note: this is after the preregistration deadline for OOPSLA. If knowing whether you've gotten into this workshop would change your decision about registering for OOPSLA, send us your paper by August 26, and we'll let you know by September 19.

What will happen at the workshop

We expect the basic structure to fall into two parts.

Talk. Selected people will make presentations based on their position paper. We’ll use the format of the Los Altos Workshop on Software Testing. It’s a moderated format, with a note-taker, that emphasizes questioning of the speaker. Questions come in two phases:

1. Clarifying questions to help the speaker explain herself.
2. Questions exploring the boundaries of the technique: upon what assumptions does it depend? in what situations does it not work?

So that probing can be thorough, presentations are not time-boxed. At the end, a list of useful techniques and generalizations will have emerged.

Voting. During a break, a small subgroup will huddle and boil the notes down to a set of propositions. The whole group will discuss each proposition in turn, possibly change the wording, and vote on it. Such discussions and votes often surface surprising opinions.

Organizers

Andy Hunt has been developing software since the early 1980's, in various senior positions at companies large and small, before becoming a consultant. He holds a BS in Information and Computer Science from the Georgia Institute of Technology and is a member of the IEEE Computer Society and the ACM. When not programming, he is an avid jazz musician and woodworker. Andy has authored two books with Dave Thomas: "The Pragmatic Programmer: From Journeyman to Master", (Addison-Wesley, 2000) and "Programming Ruby: The Pragmatic Programmer's Guide" (Addison-Wesley, 2001). They are authors of the Manifesto for Agile Software Development, and jointly edit the Construction column for IEEE Software magazine.

Brian Marick specializes in software testing, especially code-based software testing. This sometimes involves being dropped into a project near the end, having to quickly understand enough of the state of the product and the structure of the code to focus the testing effort, and then finding bugs fast. He'd like some help from the code.

Andy Schneider wears consultant and architect hats for BJSS, a software services organization. He has been involved in implementing, designing and leading projects utilizing object oriented technology since 1990. His primary interests are complex distributed systems, security and technical management.

Dave Thomas has been developing software since the mid 1970's on platforms ranging from mainframes to embedded devices. He co-founded and ran a successful software company in the United Kingdom before moving to the United States and forming the Pragmatic Programmers with Hunt. Thomas holds an honors degree in computer science from London University, and is a member of the IEEE Computer Society and the ACM. He is a keen private pilot. Together with Andy Hunt, Dave has authored two books, "The Pragmatic Programmer: From Journeyman to Master", (Addison-Wesley, 2000) and "Programming Ruby: The Pragmatic Programmer's Guide" (Addison-Wesley, 2001). They are authors of the Manifesto for Agile Software Development, and jointly edit the Construction column for IEEE Software magazine.