Mr. John J. Callan AIA wrote:

> A speaker at APT used this term, "Self-Documenting Principle".

John,

It seems to come from computer programming code practice.

"The Principle of Self-Documenting Code -- The most reliable document of 
software is the code itself. In many cases, the code is the only 
documentation. Therefore, strive to make your code self-documenting, and 
where you can't, add comments.

Self-documenting code does not get written by accident.

As developers, we must give attention to the development of a sound 
style, which is the key to self-documenting code. We must constantly try 
to improve and perfect our style, so that each program we write is 
better than the one before it. A highly developed programming style 
comes through the diligent incorporation of proven techniques: 
informative, consistent naming; modularization that pays close attention 
to cohesion and coupling; avoidance of hard to understand techniques; 
clear layout; use of named constants; testing and documenting 
assumptions; and much more.

To learn these techniques, we must read the writings of all of those who 
came before us, for these people have already blazed the trail. Seek out 
the classic literature. Learn from the masters. Subscribe to magazines. 
Join internet discussion lists. Read lots and lots of other people’s 
code. When you see code that falls short, analyze it, and try to figure 
out why. When you see code that reaches that high level we seek, you 
should be able to identify the techniques the developer used to achieve 
that level of quality. There is a saying: any fool can learn from his 
own mistakes; a wise person learns from the mistakes of others.

What about the role of comments? Do we still need them if our code is to 
be self-documenting? Self-documenting code, like perfection, is an 
elusive goal, and one that is probably impossible to achieve fully. 
However, that should not stop us from always reaching for the goal of 
self-documenting code. Where we fall short of perfection, we must 
supplement our efforts with good comments. Well written code should not 
need a lot of comments; it should speak for itself. However, some amount 
of commenting is required—the comments just need to be of the most 
useful types (see The Principle of Comments).

When viewed up close, truly self-documenting code is a joy to behold, 
and it becomes clear to the first-time observer that such a marvel could 
only occur through the efforts of a conscientious and diligent software 
engineer."

XXX

--
To terminate puerile preservation prattling among pals and the
uncoffee-ed, or to change your settings, go to:
<http://listserv.icors.org/archives/bullamanka-pinheads.html>