Just Plain Moronic

In this section, Doug relates some of his own experiences with oral documentation.

A few years ago there was an interview in Ratio Group s e-magazine ObjectiveView with Uncle Bob Martin (see Figure 7-1). In the interview, Uncle Bob stated, XPers are not afraid of oral documentation. This is one of my favorite Extremo quotes of all time. It disguises an attitude that I d sum up as We re too lazy to document our work and makes it sound like this is somehow an act of bravery and courage. What a load of crap!

Figure 7-1. XPers are not afraid of oral documentation! ^[1]

I remember exactly when this article came out, because my son Rob was about 10 years old then, and he was sitting in my office after school when he saw me busting a gut laughing at this line. A couple of days later I was driving him to school in the morning when he asked me, Dad, is oral documentation oxymoronic . . . or is it just plain moronic? I quoted him in one of my UMLWorld keynote speeches and the whole audience just completely broke up laughing.

Been There, Done That

My first programming job when I graduated college was working in the aerospace industry on some fairly mind-bending software that verified the layout of integrated circuits. This was back in the early 1980s (long before XP bounced on to the scene), and this software was some of the pioneering work in design verification for computer chips (literally the way these layouts were checked previously was to print out a plot of what the circuit would look like on a huge plotter and color in the lines with colored pencils), and the existence of this kind of software helped to enable the current generations of computer chips that we have today.

Just Slightly Ahead of His Time

My boss, Jim (who I mentioned in Chapter 1 as the inventor of the Samurai debugging technique), also was a believer in oral documentation. That is to say, he didn t bother doing any. Which was all fine until one day he decided to quit and start his own business. He had written all the original software to verify these chip layouts, and my job was to extend the work he had done to make his ideas work for a much more complex chip fabrication process (we were working on a big contract called Very High Speed Integrated Circuits).

I think Jim was an Extremo 20 years ahead of his time, because he also didn t believe in commenting his code. At least not with any comments that would mean anything to anybody other than himself. There was never a comment about why he had chosen to do something in a particular way. Oh, and he had a great fondness for cryptic acronyms as well.

I learned at a very early age how much fun it is trying to understand what somebody else was thinking when he wrote a particular piece of code and left no clues behind for whoever had to do something with that code later. Of course, because Jim left a whole bunch of undocumented work hanging around, our department was forced to hire him as a consultant so he could explain stuff that was only documented in his head. So I had some personal experience in mind when I wrote the next song.

The Long and Winding Thread

(Sing to the tune of The Long and Winding Road by The Beatles)

The long and winding thread
Leads me straight
To your code
That you wrote sitting here
A long, long time ago
You thought your code was clear
And then went out the door

Many times I ve read your code
And many times I ve cried
I wish I had a diagram
Because my brain is fried

But bugs still bring me back
To that same Piece of code
That you refactored here
Many years before
Then you stopped working here
A long, long time ago

Many times I ve read your code
And many times I ve cried
I wish I had a diagram
Because my brain is fried

Panel Members Have Lost Touch with Reality

One year at UMLWorld I was on a panel that included Uncle Bob and Martin Fowler, who were of course arguing that documentation was a waste of time, and I told the audience the story of Jim and his aversion to documentation and code comments.

It s amazing how many of the questions from the audience were related to the lack of documentation. It was obviously of concern to the people attending the conference. I remember getting my speaker evaluations back from that panel and seeing one that read, Panel members, except for Doug, have lost touch with reality.

Don t Bother Me, I m Busy ³Go Watch the Videotape

Documentation doesn t have to be heavyweight, 600-page volumes , though. A few years later in my programming career I was working on another Very Large Scale Integration (VLSI) project, this one involving an automatic router for wiring up chips. I needed to extend this router, which already existed, to do some stuff it had never been designed to do.

It was a fairly complex piece of software, and it used a data structure called a quad-tree. (The quad-tree is similar to a binary tree, but each node points at four children instead of two. It s very useful for two-dimensional graphics, such as maps and integrated circuit layouts.) The quad-tree package had been written by a less gregarious programmer (I mentioned him in Chapter 6 as being a brilliant programmer with whom I wouldn t have been able to share a keyboard).

This fellow (I ll call him Bret because that s his name ) didn t want to be bothered with people asking him questions about how his quad-tree software worked, so what he had done was to stand up in front of a whiteboard and explain how it worked to a video camera. When I started on the project, he told me to go watch the tape. I did, and I learned how it worked, and I was able to use it very effectively.

It could be argued that this was oral documentation, but a better term might be video documentation, because he was recording to something rather more permanent than thin air.

Years later, when I was managing a team of programmers who were building a suite of CASE tools at ICONIX, I needed to get a fairly complex piece of code written. I believe it was a spline package to draw smooth curves through a series of points for our dataflow diagram editor. Which of my two ex-workmates (I would characterize both of them as brilliant programmers) do you think I called? (Hint: Not the one who relied on oral documentation ”that is to say, no documentation.) I gave Bret the requirements and let him work from home, undisturbed. He produced quite a lovely piece of code ”very efficient, well commented, and bug-free.

The point here is that it is really important to leave some nontransient form of explanation of the intention of the designer behind. The form of that explanation can be comments, UML, or videotape. But it has to be nontransient. Some permanent, enduring , nontransient record of the thought process (besides the source code) has to exist, somewhere. Ideally, if you learn to design using tools like UML, the design activity itself leaves the trail of breadcrumbs you need without a lot of extra effort.

And What About the New Programmer Who Gets Hired Midstream?

As we discussed earlier in this chapter, this idea that documentation isn t necessary until someone outside the team needs to understand what s going on, can all too easily be used as a job security program for the XP team.

Think about it: An unsuspecting manager hires a team of XPers, thinking that the world s most agile process will get her software delivered on schedule. Somewhere along the way she learns that SoftwareIsNeverDone and the schedule does not exist per se. Can she consider replacing the development team? Well, nothing is written down about the design . . . hmm. Obscurity = job security?

See Chapter 11 for a discussion of the slightly surreal Extremo philosophies SoftwareIsNeverDone and the schedule does not exist per se.

 

Freedom from documentation is almost certainly one of the prime factors in XP s wild popularity among cowboy coders. These are the folks who say they re doing XP, but they aren t pair programming, unit testing, and so on. They re just bravely not documenting their work. Which leads us to our next Voice of eXPerience section.

VoXP
Voice of eXPerience: Oral Documentation

by Timothy Fisher

The lack of documentation on our project was a significant issue. I felt that it seriously impacted my ability to quickly come up to speed on the project when I joined the group. There were literally no documents or diagrams that I could look at to understand the implementation at a high level. I was immediately pointed to the code upon asking any questions that I had about the architecture or design.

I hadn t heard the term oral documentation before and I can t say that they used oral documentation. They just tended to believe that no documentation was necessary. They had the mind-set , which I know is common in XP, that the code itself should be all the documentation necessary for the project. There are so many problems with that attitude that I could go on and on about. For one, it provides nothing for the managers and higher-ups to understand the implementation. They certainly aren t going to sit down and go through the code. Although well-written code can serve as good code-level documentation and can be self-describing , it certainly doesn t provide the architectural overview or any insight into the structure and design of the code and code components .

This issue again goes back to what I think is a fundamental flaw in the XP methodology, in that it s an extremely code-centric methodology that leaves little room for analysis and design, and certainly no framework that would mandate any design at all. You could complete a project following all of the tenets of XP and end up with zero documentation and no clear overall structure to the design. Although the code may be well written at the class level, and it may be well tested and even apparently successful, over time the flaws in the XP process will begin to show themselves when the maintenance phases begin.

 

Unit Tests Are Documentation (Yeah, Right)

Unit tests are an integral part of test-first design, which is an integral part of XP. But are unit tests ( coupled with the actual source code) a sufficient substitute for design documentation? (See Figure 7-2.)

Figure 7-2. Unit tests are also documentation. ^[16]

XPers use the design mantra you aren t gonna need it (YAGNI). This design mantra drives the theory behind emergent design ”that you design and code for the current 2-week iteration and turn a blind eye to any possible future design concerns. In the context of design documentation, you might think that YAGNI is a pretty good reason to avoid writing documents; otherwise , there d be a lot of documentation to update.

We cover test-first design in the next chapter and emergent design in Chapter 12.

 

Ironically, however, written statements of intent are much more important in an evolving design because they record the overall direction that the codebase is intended to head in. These documents are written at a higher level of abstraction than the source code (the only permanent XP design artifact). Therefore, design documents need additional information to describe the theory behind a particular design. This removes the temptation to add extra comments to the code or to clutter the source with code stubs ^[16] as placeholders for intended future functionality.

Oral documentation also becomes a cultural epithet for the real thing in the Extremo world. Consider, for example, this quote from XProgramming.com:

GROUCHO  

It is common for XP teams to have some pictures of the system s design on the wall for extended periods. I observe that these seem to serve more as decoration than as documentation: people don t look at them very often. They ask each other, or they pair program with someone who knows the answer. ^[17]

A programmer/contractor friend, Dino Fancellu, e-mailed me his opinion of oral documentation. I ve reprinted the e-mail here in full:

Re lack of documentation: This is exactly the opposite of what I do, the teleworker. I can t afford to have endless cozy chitchats about how I feel like coding today.

Everything I do is given to me via email, bounced back and forth, polished, verified, until I m sure it is what they want, and more importantly, what they need.

I can t abide people telling me to do things on the phone, as I know they will forget, and so will I. I m only human, and the bigger and more complex the project the more I will forget, the more I will misinterpret.

Even if I get sign off after a thought clearing phone call I ll make sure I get a verifying email. I ve worked this way for years, all on successful projects.

XP seems to do little for teleworkers. And don t even get me started on pair programming! ^[18]

More from Dino in the section Wishing for the Sound of Silence in Chapter 6.

With some effort, it is possible to patch the XP process to allow for distributed teams (such as telecommuters). However, this typically involves significant additional design documentation and a rethink of the way that the on-site customer works ”thus, the main benefits of XP are lost.

We discuss the effect of distributed teams on XP in Chapter 14.

 

Without proper design documentation, avid YAGNIers run the risk of losing sight of their original goal, forgetting why a design was originally being launched in a particular direction. As we discussed in the previous chapter, pair programming is an important XP safety net to prevent this from happening. Another snake threatens to break loose.

UML Won t Write My Code

(Sing to the tune of Can t Buy Me Love by The Beatles)

Won t write my code
UML won t write my code
Won t write my code
No, no, no, no

Say you want me to use UML
I say it s a waste of time
I d rather go by the code smell

Cause the code is the design
I don t care for UML diagrams
Cause UML won t write my code

Won t write my code
UML won t write my code
Won t write my code
No, no, no, no

You say you want me to document
Well I ll tell you hell no
It s a waste of time to document
I m not afraid to tell you so
Why the hell would I want to document
When I could be writing code

Just writing code
Cause it s really all I know
Just writing code
Go, go, go, go

FANGS  

Fangs Is on the Loose Again

Oral documentation can lead to lack of focus, Constant Refactoring After Programming, and software that is never done, because people generally don t remember the same details in exactly the same way. This affects both the design and the requirements.

Also see the section Embrace Rampant Scope Creep Regularly in Chapter 11.

 

The oral documentation snake is theoretically kept at bay by pair programming, collective ownership, and colocated teams (including the on-site customer). The theory is that the team collectively knows the design and doesn t have to shout very far across the room in order to communicate it, and the customer knows all 1,000 requirements in detail and carries them around in his gargantuan head. Therefore, the need for permanent documentation is significantly less. That is, until one of the dependent snakes starts to slip.

 

SOLUTION  

Oral Documentation Defanged

Many of the problems associated with XP can be solved with the simple introduction of clear, concise , unambiguous documentation (for both requirements and design).

Design documentation is valuable at so many levels ( especially when it is produced as a by-product of the design process) because it encourages the team to think the design through in exacting detail.

We discuss how to make detailed design documentation a byproduct of the design process in Chapter 8.

 

This can help prevent endless refactoring (where the project spins out into refactoring eddies without really completing very many new requirements ”in other words, the project velocity is very low). XP relies heavily (too heavily, we believe) on osmotic communication (e.g., knowledge sharing via pair programming or overhearing two programmers discussing a design issue) to keep everyone up-to-date on the latest design decisions. Keeping an up-to-date written design lessens this dependence, so that osmotic communication becomes a nice-to-have rather than a must-have -or-we-all-go-off-the-rails.

Written requirements ”fleshed out, clarified, and signed off before productioncoding begins ”help immensely in keeping a project focused and on track, working toward a well-defined , unambiguous set of goals.

Ambiguity sinks projects. If a requirement is ambiguous, get clarification and then update the written requirements.

Put the requirements onto a project intranet (even aWiki) so that everybody has access to them. Start with a definition of the goals of the project, and make sure every requirement can be traced back to at least one of the goals. If a goal changes during the project, change the goal, but treat this as the big deal that it really is. Any requirements that trace back to that goal will probably also need to be revisited to ensure they re still relevant to the project.

Recognizing how many requirements are really based on a particular goal sure helps to keep the project focused. This may be seen as nonagile because of the additional documentation required, but in reality it s a way of identifying and remembering the true lines of dependency between goals, requirements, and implementation tasks (these lines exist in any project, even XP projects). Pretending they re not there means potentially storing up trouble and spinning a project that s completely lacking in focus.

 

^[1] See http://www.ratio.co.uk/ov4.pdf.

^[16] Figure 7-2 states that inside the team, [unit tests] are typically enough code documentation. Well, suppose the team quits, or management isn t happy with the team s performance and wants to replace its members. That s the primary scenario where documentation for somebody outside the team would be required. We see the lack of said documentation as the cause of the So bite me! attitude that we discussed earlier in this chapter in the Documenting for the Future section.

^[16] XP discourages the practice of adding code stubs for functionality that is not in the current iteration. If the design is evolving, though, there may still be a temptation to add intentionrevealing code or comments so that programmers in future iterations catch on to the direction that that part of the design is headed in. .

^[17] Ron Jeffries, Essential XP: Documentation, op.

^[18] Dino Fancellu, e-mail to author, November 2002.