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>
|