©2000-2017 Roedy Green of Canadian Mind Products
Any fool can tell the truth, but it requires a man of some sense to know how to lie
~ Samuel Butler (1835-12-04 1902-06-18 age:66)
Incorrect documentation is often worse than no documentation.
~ Bertrand Meyer (1950 age:67),
creator of design by contract and the Eiffel language.
Since the computer ignores comments and documentation, you can lie outrageously and do
everything in your power to befuddle the poor maintenance programmer.
Lie in the comments
: You don’t have to actively lie, just fail to keep
comments as up to date with the code.
Document the obvious
: Pepper the code with comments like however, never document wooly stuff like the
overall purpose of the package or method.
Document How Not Why
: Document only the details of what a program does, not
what it is attempting to accomplish. That way, if there is a bug, the fixer will have
no clue what the code should be doing.
Avoid Documenting the Obvious
: If, for example,
you were writing an airline reservation system, make sure there are at least 25
places in the code that need to be modified if you were to add another airline. Never
document where they are. People who come after you have no business modifying your
code without thoroughly understanding every line of it.
On the Proper Use of Documentation Templates
: Consider function
documentation prototypes used to allow automated documentation of the code. These
prototypes should be copied from one function (or method or class) to another, but
never fill in the fields. If for some reason you are forced to fill in the fields
make sure that all parameters are named the same for all functions and all cautions
are the same but, of course, not related to the current function at all.
On the Proper Use of Design Documents
: When implementing a very complicated
algorithm, use the classic software engineering principles of doing a sound design
before beginning coding. Write an extremely detailed design document that describes
each step in a very complicated algorithm. The more detailed this document is, the
In fact, the design doc should break the algorithm down into a hierarchy of
structured steps, described in a hierarchy of auto-numbered individual paragraphs in
the document. Use headings at least 5 deep. Make sure that when you are done, you
have broken the structure down so completely that there are over 500 such
auto-numbered paragraphs. For example, one paragraph might be: (this is a real
126.96.36.199.3.13 — Display all impacts for activity where selected mitigations
can apply (short pseudocode omitted).
then… (and this is the kicker) when you write the code,
for each of these paragraphs you write a corresponding
Do not document these functions. After all, that’s what the design document is
Since the design doc is auto-numbered, it will be extremely difficult to keep it
up to date with changes in the code (because the function names, of course, are
static, not auto-numbered.) This isn’t a problem for you because you will not
try to keep the document up to date. In fact, do everything you can to destroy all
traces of the document.
Those who come after you should only be able to find one or two contradictory,
early drafts of the design document hidden on some dusty shelving in the back room
near the dead 286 computers.
Units of Measure
: Never document the units of measure of any variable,
input, output or parameter, e. g. feet, metres, cartons. This is not so important in
bean counting, but it is very important in engineering work. As a corollary, never
document the units of measure of any conversion constants, or how the values were
derived. It is mild cheating, but very effective, to salt the code with some
incorrect units of measure in the comments. If you are feeling particularly
malicious, make up your own unit of measure; name it after yourself
or some obscure person and never define it. If somebody challenges you, tell them you
did so that you could use integer rather than floating point arithmetic.
: Never document gotchas in the code. If you suspect there may be a
bug in a class, keep it to yourself. If you have ideas about how the code should be
reorganised or rewritten, for heaven’s sake, do not write them down. Remember
the words of Thumper in the movie Bambi "If you can’t say anything
nice, don’t say anything at all". What if the programmer who wrote
that code saw your comments? What if the owner of the company saw them? What if a
customer did? You could get yourself fired. An anonymous comment that says
This needs to be fixed! can do wonders, especially if
it’s not clear what the comment refers to. Keep it vague and nobody will feel
: Never put a comment on a variable
declaration. Facts about how the variable is used, its bounds, its legal values, its
implied/displayed number of decimal points, its units of measure, its display format,
its data entry rules (e.g. total fill, must enter), when its value can be trusted
etc. should be gleaned from the procedural code. If your boss forces you to write
comments, lard method bodies with them, but never comment a variable declaration, not
even a temporary!
Disparage In the Comments
: Discourage any attempt to use external
maintenance contractors by peppering your code with insulting references to other
leading software companies, especially anyone who might be contracted to do the work,
If possible, put insulting stuff in syntactically significant parts of the code, as
well as just the comments so that management will probably break the code if they try
to sanitise it before sending it out for maintenance.
COMMENT AS IF IT WERE CØBØL ON PUNCH CARDS
: Always refuse to
accept advances in the development environment arena, especially SCIDs. Disbelieve rumors that all function and variable
declarations are never more than one click away and always assume that code developed
in Visual Studio 6.0 will be maintained by someone using edlin or vi. Insist on
Draconian commenting rules to bury the source code proper.
Monty Python Comments
: On a method called makeSnafucated insert
only the Javadoc . Never define
what snafucated means anywhere. Only a fool does
not already know, with complete certainty, what snafucated means. For
classic examples of this technique, consult the Sun AWT (Advanced Windowing Toolkit)
Be sure to comment out unused code instead of deleting it and
relying on version control to bring it back if necessary. In no way document whether
the new code was intended to supplement or completely replace the old code, or
whether the old code worked at all, what was wrong with it, why it was replaced etc.
Comment it out with a lead and trail rather than a on each line. That
way it might more easily be mistaken for live code and partially maintained.