theparticle.com

ALPHA v0.3

Disclaimer
Because of the fun and sarcastic nature of some of these jokes, viewer & reader discretion is advised. Don't read'em and then complain!

Alpha
This is an alpha release of this section. If you find any problems or would like to recommend something, please be kind enough to give us some feedback.


BACK

How To Write Unmaintainable Code

Topic: programming

How To Write Unmaintainable Code

Last updated 1997 May 23 by Roedy Green (C) 1997 Canadian Mind Products.

In the interests of creating employment opportunities in the Java programming field, I am passing on these tips from the masters on how to write code that is so difficult to maintain, that the people who come after you will take years to make even the simplest changes. Further, if you follow all these rules religiously, you will even guarantee yourself a lifetime of employment, since no one but you has a hope in hell of maintaining the code.

Lie in the comments. You don't have to actively lie, just fail to keep comments as up to date with the code.

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

Make sure that every method does a little bit more (or less) than its name suggests. As a simple example, a method named isValid(x) should as a side effect convert x to binary and store the result in a database.

Use acronyms to keep the code terse. Real men never define acronyms; they understand them genetically.

In the interests of efficiency, avoid encapsulation. Callers of a method need all the external clues they can get to remind them how the method works inside.

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.

In the name of efficiency, use cut/paste/clone. This works much faster than using many small reusable modules.

Never never put a comment on a variable. 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 code. If your boss forces you to write comments, lard method bodies with them, but never comment a variable, not even a temporary!

Try to pack as much as possible into a single line. This saves the overhead of temporary variables, and makes source files shorter by eliminating new line characters and white space. Tip: remove all white space around operators. Good programmers can often hit the 255 character line length limit imposed by some editors. The bonus of long lines is that programmers who cannot read 6 point type must scroll to view them.

Cd wrttn wtht vwls s mch trsr. When using abbreviations inside variable or method names, break the boredom with several variants for the same word, and even spell it out longhand once in while. This helps defeat those lazy bums who use text search to understand only some aspect of your program. Consider variant spellings as a variant on the ploy, e.g. mixing International colour, with American color and dude-speak kulerz.

Never use an automated source code tidier to keep your code aligned. Lobby to have them banned them from your company on the grounds they create false deltas in PVCS (version control tracking). You are now free to accidentally misalign the code to give the optical illusion bodies of loops and ifs are longer or shorter than they really are.

Rigidly follow the guidelines about no goto, no early returns, and no labelled breaks especially when you can increase the if/else nesting depth by at least 5 levels.

Use very long variable names that differ from each other by only one character, or only in upper/lower case. Wherever scope rules permit, reuse existing unrelated variable names. An ideal variable name pair is swimmer and swimner. Exploit the failure of most fonts to clearly discriminate between ilI1| or oO08 with identifier pairs like parselnt and parseInt or D0Calc and DOCalc.

Never use i for the innermost loop variable. Use anything but. Use i liberally for any other purpose especially for non-int variables.

Never use local variables. Whenever you feel the temptation to use one, make it into an instance or static variable instead to unselfishly share it with all the other methods of the class. This will save you work later when other methods need similar declarations. C++ programmers can go a step further by making all variables global.

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

To break the boredom, use a thesaurus to look up as much alternate vocabulary as possible to refer to the same action, e.g. display, show, present. Vaguely hint there is some subtle difference, where none exists. However, if there there are two similar functions that have a crucial difference, always use the same word in describing both functions (e.g. print to mean write to a file, and to a print on a laser, and to display on the screen). Under no circumstances, succumb to demands to write a glossary with the special purpose project vocabulary unambiguously defined. Doing so would be unprofessional breach of the the structured design principle of information hiding.

In naming functions, make heavy use of abstract words like it, everything, data, handle, stuff, do, routine, perform and the digits e.g. routineX48, PerformDataFunction, DoIt, HandleStuff and do_args_method.

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.

In engineering work there are two ways to code. One is to convert all inputs to S.I. (metric) units of measure, then do your calculations then convert back to various civil units of measure for output. The other is to maintain the various mixed measure systems throughout. Always choose the second. It's the American way!

I am going to let you in on a little-known coding secret. Exceptions are a pain in the behind. Properly-written code never fails, so exceptions are actually unnecessary. Don't waste time on them. Subclassing exceptions is for incompetents who know their code will fail. You can greatly simplify your program by having only a single try/catch in the entire application (in main) that calls System.exit(). Just stick a perfectly standard set of throws on every method header whether they could throw any exceptions or not.

C compilers transform myArray[i] into *(myArray + i), which is equivalent to *(i + myArray) which is equivalent to i[myArray]. Experts know to put this to good use. Unfortunately, this is of historical interest only for Java programmers.

Eschew any form of table-driven logic. It starts out innocently enough, but soon leads to end users proofreading and then shudder, even modifying the tables for themselves.

Nest as deeply as you can. Good coders can get up to 10 levels of ( ) on a single line and 20 { } in a single method. C++ coders have the additional powerful option of preprocessor nesting totally independent of the nest structure of the underlying code. You earn extra Brownie points whenever the beginning and end of a block appear on separate pages in a printed listing. Wherever possible, convert nested ifs into nested [? :] ternaries.

Join a computer book of the month club. Select authors who appear to be too busy writing books to have had any time to actually write any code themselves. Browse the local bookstore for titles with lots of cloud diagrams in them and no coding examples. Skim these books to learn obscure pedantic words you can use to intimidate the whippersnappers that come after you. Your code should impress. If people can't understand your vocabulary, they must assume that you are very intelligent and that your algorithms are very deep. Avoid any sort of homely analogies in your algorithm explanations.

I have saved the best for last. From a psychological warfare point of view, this is the most effective weapon for rattling maintenance programmers. On a method called makeSnafucated insert only the comment /* make snafucated */. Never define what snafucated means anywhere. Only a fool does not already know, with complete certainty, what snafucated means.

Contributors

The following are some of the people who contributed to this list. My lawyers recommended I exclude those who taught by example.

Hugh McDonald, BC Hydro

Gareth Meyrick, gareth@pangloss.ucsf.edu

Jarle Stabell, jarle.stabell@dokpro.uio.no

Ko-Haw Nieh, niko@quality.com

Jim Johnson, jimj@jumpmusic.com


ALPHA v0.3