Documentation

• You are here :
• home
• Java Glossary
• Unmaintainable Code
• Documentation
•  

“Any fool can tell the truth, but it requires a man of some sense to know how to lie well.”
~ Samuel Butler (1835 - 1902)

“Incorrect documentation is often worse than no documentation.”
~ Bertrand Meyer

Since the computer ignores comments and documentation, you can lie outrageously and do everything in your power to befuddle the poor maintenance programmer.

1. Lie in the comments

   : You don’t have to actively lie, just fail to keep comments as up to date with the code.

2. Document the obvious

   : Pepper the code with comments like /* add 1 to i */ however, never document wooly stuff like the overall purpose of the package or method.

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

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

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

6. 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 better.

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

   1.2.4.6.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 global function named:

   Act1_2_4_6_3_13()

   Do not document these functions. After all, that’s what the design document is for!

   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.

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

8. Gotchas

   : 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 personally criticised.

9. Documenting Variables

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

10. 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. e.g.:
    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.

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

12. Monty Python Comments

    : On a method called makeSnafucated insert only the Javadoc /* make snafucated */. 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 Javadoc.

13. Obsolete Code

    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.

	Please email your feedback for publication, errors, omissions, broken/redirected link reports and suggestions to improve this page to Roedy Green :
	Canadian Mind Products
	mindprod.com IP:[65.110.21.43]
	Your face IP:[38.103.63.16]	The information on this page is for non-military use only.
	You are visitor number 88,563.	Military use includes use by defence contractors.
	You can get a fresh copy of this page from:	or possibly from your local J: drive (Java virtual drive/Mindprod website mirror)
	http://mindprod.com/jgloss/unmaindocumentation.html	J:\mindprod\jgloss\unmaindocumentation.html