"It's easier for programmers to talk to each other than to document"

by Conrad Weisert, April 10, 2006
© Information Disciplines, Inc., Chicago

NOTE: This article may be circulated freely as long as the copyright notice is included.

A 40-year trend?

The title of this article is a verbatim quote from a presentation last week by a proponent of the so-called agile approach to programming. He went on to opine that talking is not only easier than documenting, but also more productive in advancing software development. The speaker also asserted that most documentation written by programmers is produced mainly in order to satisfy an organization's "bureaucracy".

If many members of the audience were shocked, they didn't show it. Minimal documentation is now taken for granted as an accepted component of a modern approach to developing application systems and software products.

Among reluctant coders and revisionist methodologists that view is hardly new. Some of them have been struggling to find excuses to avoid documenting ever since documentation was first mentioned as an essential aspect of high-quality software. One classic objection from 1965 came from a prolific creator of monolithic COBOL monsters: "You don't want to put too much commentary in your programs, because the compiler will take too much time passing over it." And some of us still remember that COBOL was at first touted as a self documenting programming language that any manager could understand, thus relieving programmers of having to explain their module designs or their code.

Good documentation and bad documentation

Last week's speaker went on to clarify his assertions by conceding that with an agile methodology we may need some documentation, but only when it can be shown that there's a known audience who will actually read and make good use of it. We mustn't waste time creating "documentation for the sake of documentation" he warned.

This is new?

I've been working with and helping to develop methodologies throughout the eras that introduced into the mainstream the phased life cycle, structured methods, object orientation, and many other practices. At no time did I or my colleagues suggest that system developers should produce any document that didn't have both a target audience and a definite present or future use.

Granted, some organizations did embrace over-formal, perhaps bureaucratic standards. And a few vendors of proprietary methodology materials, courses, and C.A.S.E. tools went overboard in trying to standardize everything that could possibly be standardized and to document everything that could possibly be documented. But such misguided extremes were never the mainstream. It's irresponsible to cite them as excuses for abandoning all discipline in system development.

Experience has shown that a participative approach to in-house methodology, given competent staff, is likely to avoid the extremes of both bureaucratic over-formalization and chaotic anarchy.

Kinds of documentation and their audiences

Documenting for yourself

An obvious flaw in the easier-to-talk-to-each-other argument is that it fails to cater to staff turnover. I may share or exchange knowledge with my project teammates effectively, but two years from now when some of us have moved on, our successors will still need to be oriented.

Even without turnover, however, we still need to document for another audience: ourselves. When I pick up a piece of software that I developed three years ago, I may not grasp the rationale behind the structure, the choice of algorithm, or certain techniques. If I'm busy working on multiple tasks, I may even have trouble recalling exactly what I did a week ago.

We document our internal design and our code for the general audience of maintenance programmers, who may be either people new to the project or our future selves.

A "document-first" approach to programming

One of the main components of agile methods is the test-first approach to unit testing. If you write the test drivers before you develop a module you'll then focus on writing the simplest code that makes those test drivers get the right results.

An even stronger case can be made for writing module1 documentation before you write code. Commentary in a source-code listing falls into four categories:

  1. Identifying infomation: a descriptive title along with the name of the author or copyright holder.
  2. Introductory comments: a explanation of what the module does, how it's used, and the general strategy or algorithm.
  3. Block comments: Paragraphs interspersed with the code to affirm the state of a computation at that point or describe the next steps to be carried out.
  4. Line by line comments: Explanations of any program statements whose purpose is not obvious from the code itself.

A good programmer finds the act of writing the introductory comments a huge help in clarifying his or her thoughts before starting to write code. After I've stated in precise and unambiguous terms exactly what my module is going to do, writing the code is usually a straightforward exercise, and I'm unlikely to waste effort in trial-and-error flailing.

I advise my students to write the introductory (#1 & #2 above) source code commentary before writing any code, and then to write a block paragraph (#3 above) to clarify their own thoughts whenever the code is getting too complicated to grasp easily. The line-by-line commentary, if needed, can be written at any time.

In a companion article I show an example of the document-first process at the individual function level.

The requirements crisis

Among extremists who think we don't need systems analysts to document formal requirements for new application systems, a current fad is to declare the collection of acceptance test cases to serve as the formal specification of the proposed system. The extremists argue that if:

then the users will be satisfied. Any requirements documentation, therefore, would be redundant, unnecessary, and eventually obsolete.

Knowledgeable systems people will chuckle at the naïveté of such a strategy. There's a lot more to a complete business system than can be validated by a bunch of inputs and corresponding results. Besides, how can non-technical end users grasp the scope of an unstructured pile of test cases, much less spot omissions and inconsistencies?

User documentation

We've been discussing above requirements documentation, design documentation, and maintenance documentation. In addition, both application systems and software products need documentation for the prospective users, which may consist of:

Presumably even the most extreme opponents of documenting concede the need for usage documentation appropriate to the nature of the application and the backgrounds of the prospective users. The need for users' documentation, we hope, remains non-controversial.

The skills issue

People like to do what they're good at. Programmers who can organize their thoughts coherently and express them clearly are seldom reluctant to document their designs and their code. Competent systems analysts take satisfaction in producing concise and unambiguous specifications that both end users and developers can easily understand.

The growing popularity of documentation-free methodologies is driven both by marginally competent people who have trouble organizing and expressing clear thoughts and by methodologists overeager to be on the leading edge of something new. Are those the people we trust to develop high-quality systems?

1 -- By "module" here we mean any manageable unit of code. A module can be an individual subroutine or function, an object-oriented class definition, a package of macro definitions, or any other collection of computer code worth developing as a unit.

Return to IDI home page
technical articles
methodology materials

Last modified April 11, 2006