1. Introduction
While my experience as an editor has led me to a disdain for lengthy prose and complex logic, I believe, if you will extend your patience for just a moment, you will find there is a method to this tale.
Programmers want to have fun. Designing and creating software is a creative activity that can be deeply satisfying — so much so that good programmers often find themselves spending their weekends and vacation time programming (e.g. writing their own software, or collaborating with others on projects that attract them) — not because they have to, but because doing a good job at it (stressed) and knowing that you are delivering high value to others, is deeply rewarding, both mentally and spiritually. When such reward is involved, assuming his relationship with his co-workers is good, a programmer looks forward to getting up and going to work each day. Why? Quite literally because it is both fun and satisfying.
Let us take a careful look at the ingredients of this fun and satisfaction, because they are important to understanding the motive behind producing high-quality code documentation. As a programmer, you are creating something that:
you are proud of because
it is of high quality, and
has high value to others.
I believe you will find that such satisfaction is true of virtually any production activity, whether you are providing a service, or creating something you give to others.
In contrast, when the above ingredients are not present for a programmer, programming can feel like “a chore”, and can be not fun to the degree that these ingredients are missing. (Interpersonal workplace relationships are beyond the scope of this work.)
Let us look for a moment at the middle ingredient: quality.
1.1. What Factors Give Quality to Source Code?
1.1.1. External vs Internal Quality Factors
External quality factors such as speed and ease of use are those properties of software (including the source code used to build it) that are perceived by its end users. End users are not only people directly using that software, but also the executives in charge of arranging for that software to be used by their companies.
Internal quality factors (such as modularity and readability) are properties of software that are perceptible only by computer professionals who have access to the source code itself.
These qualities are well known and well documented in many places, one of the best of which is Bertrand Meyer’s Object-Oriented Software Construction [Meyer1997]. In this famous work, Meyer astutely points out the vital relationship between external and internal quality factors:
“In the end, only the external factors matter. If I use a Web browser or live near a computer-controlled nuclear plant, little do I care whether the source program is readable or modular if graphics take ages to load, or if a wrong input blows up the plant. But the key to achieving these external quality factors lies in the internal quality factors: for the users to enjoy the visible qualities, the designers and implementers must have applied internal techniques that will ensure the hidden qualities. ... We should not, however, lose track of the global picture; the internal techniques are not an end in themselves, but a means to reach external software qualities. So we must start by looking at external factors.”
I won’t beat a dead horse here by thoroughly re-hashing the detail of these quality factors, since they are well explained in Chapter 1 of [Meyer1997], but I will list them here briefly for a quick review. And while we’re at it, we’re going to add a little twist: instead of applying them to “software in general”, we are applying these quality factors specifically to source code.
1.1.2. External Quality Factors
The following is a list of source-code properties as viewed by its end users. Remember that its end users are programmers who are:
- API users:
programmers who are merely using a body of source code as a component of a larger system (e.g. a popular open-source graphics library, as it might apply to a touch-screen automotive dashboard application); or
- maintainers:
programmers that need to thoroughly understand what that source code does and how it works, so they can safely add features and/or make changes to it without introducing new bugs.
Here are the external quality factors from [Meyer1997]:
Note that timeliness relies heavily on a source-code quality factor which is not listed above: to achieve timeliness, the reliability of the source code needs to be such that when a part of that source code is used for the first time, such as when a new feature is being added to a system, the risk of introducing new bugs to the system is very low. Thus, I am adding one additional external quality factor applicable to source code:
1.1.2.1. Competing Quality Factors
Meyer further points out:
“In this review of external software quality factors, we have encountered requirements that may conflict with one another.
“How can one get integrity without introducing protections of various kinds, which will inevitably hamper ease of use? Economy often seems to fight with functionality. Optimal efficiency would require perfect adaptation to a particular hardware and software environment, which is the opposite of portability, and perfect adaptation to a specification, where reusability pushes towards solving problems more general than the one initially given. Timeliness pressures might tempt us to use “Rapid Application Development” techniques whose results may not enjoy much extendibility.
“Although it is in many cases possible to find a solution that reconciles apparently conflicting factors, you will sometimes need to make tradeoffs. Too often, developers make these tradeoffs implicitly, without taking the time to examine the issues involved and the various choices available; efficiency tends to be the dominating factor in such silent decisions. A true software engineering approach implies an effort to state the criteria clearly and make the choices consciously.
“Necessary as tradeoffs between quality factors may be, one factor stands out from the rest: correctness. There is never any justification for compromising correctness for the sake of other concerns such as efficiency. If the software does not perform its function, the rest is useless.”
1.1.2.2. Key External Qualities
While all of the above qualities are important, four stand out:
1.1.3. Internal Quality Factors
The following are Bertrand Meyer’s list of software properties that are perceptible only to computer professionals who have access to the source code itself.
It is very easy to see by any professional programmer that these are all important quality factors of source code, and that software quality relies heavily on the quality of its source code.
For source code that will spend most of its life under maintenance, there is one more important quality of source code however, that does not appear in the above lists, nor have I seen it appear on anyone else’s source-code quality list, and I consider this an important omission....
For source code that will spend most of its life under maintenance, understandability is one of the most important qualities of source code, after correctness, and enhances many other factors of source-code quality:
1.1.4. Summary
Programmers want to have fun (as does anyone involved in a production activity).
Knowing that one is delivering high value to others is a key component of having fun as a programmer.
Software quality relies heavily on the quality of its source code.
Documentation, especially when written before the source code, can play an important role in source-code correctness, the most important quality. (See Articles on Documentation-Driven Development)
For source code that will spend most of its life under maintenance:
Understandability is one of the most important qualities of source code, after correctness, and enhances many other factors of source-code quality.
Good documentation is a major component of understandability.
- Good documentation is therefore:
an important component high-quality source code
an important component of having fun as a programmer.