How To Write Unmaintainable Code

Ensure a job for life ;-)

Roedy Green Canadian Mind Products

Reproduced with permission from the author, circa 2015

---

Introduction

Never ascribe to malice, that which can be explained by incompetence. - Napoleon

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. Then again, if you followed all these rules religiously, even you wouldn't be able to maintain the code!

You don't want to overdo this. Your code should not look hopelessly unmaintainable, just be that way. Otherwise it stands the risk of being rewritten or refactored.

General Principles

Quidquid latine dictum sit, altum sonatur. - Whatever is said in Latin sounds profound.

To foil the maintenance programmer, you have to understand how he thinks. He has your giant program. He has no time to read it all, much less understand it. He wants to rapidly find the place to make his change, make it and get out and have no unexpected side effects from the change.

He views your code through a toilet paper tube. He can only see a tiny piece of your program at a time. You want to make sure he can never get at the big picture from doing that. You want to make it as hard as possible for him to find the code he is looking for. But even more important, you want to make it as awkward as possible for him to safely ignore anything.

Programmers are lulled into complacency by conventions. But every once in a while, by subtly violating convention, you force him to read every line of your code with a magnifying glass.

You might get the idea that every language feature makes code unmaintainable -- not so, only if properly misused.

Naming

"When I use a word," Humpty Dumpty said, in a rather scornful tone, "it means just what I choose it to mean - neither more nor less."

• Lewis Carroll -- Through the Looking Glass, Chapter 6

Much of the skill in writing unmaintainable code is the art of naming variables and methods. They don't matter at all to the compiler. That gives you huge latitude to use them to befuddle the maintenance programmer.

New Uses For Names For Baby

Buy a copy of a baby naming book and you'll never be at a loss for variable names. Fred is a wonderful name, and easy to type. If you're looking for easy-to-type variable names, try asdf or aoeu if you type with a DSK keyboard.

Single Letter Variable Names

If you call your variables a, b, c, then it will be impossible to search for instances of them using a simple text editor. Further, nobody will be able to guess what they are for. If anyone even hints at breaking the tradition honoured since FØRTRAN of using i, j, and k for indexing variables, namely replacing them with ii, jj and kk, warn them about what the Spanish Inquisition did to heretics.

Creative Miss-spelling

If you must use descriptive variable and function names, misspell them. By misspelling in some function and variable names, and spelling it correctly in others (such as SetPintleOpening and SetPintalClosing) we effectively negate the use of grep or IDE search techniques. It works amazingly well. Add an international flavor by spelling tory or tori in different theatres/theaters.

Be Abstract

In naming functions and variables, 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.

A.C.R.O.N.Y.M.S.

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

Thesaurus Surrogatisation

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 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", "put ink on paper" and "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 an unprofessional breach of the structured design principle of information hiding.

Use Plural Forms From Other Languages

A VMS script kept track of the "statii" returned from various "Vaxen". Esperanto , Klingon and Hobbitese qualify as languages for these purposes. For pseudo-Esperanto pluraloj, add oj. You will be doing your part toward world peace.

CapiTaliSaTion

Randomly capitalize the first letter of a syllable in the middle of a word. For example ComputeRasterHistoGram().

Reuse Names

Wherever the rules of the language permit, give classes, constructors, methods, member variables, parameters and local variables the same names. For extra points, reuse local variable names inside {} blocks. The goal is to force the maintenance programmer to carefully examine the scope of every instance. In particular, in Java, make ordinary methods masquerade as constructors.

Åccented Letters

Use accented characters on variable names. E.g.

typedef struct { int i; } ínt;

where the second ínt's í is actually i-acute. With only a simple text editor, it's nearly impossible to distinguish the slant of the accent mark.

Exploit Compiler Name Length Limits

If the compiler will only distinguish the first, say, 8 characters of names, then vary the endings e.g. var_unit_update() in one case and var_unit_setup() in another. The compiler will treat both as var_unit.

Underscore, a Friend Indeed

Use _ and __ as identifiers.

Mix Languages

Randomly intersperse two languages (human or computer). If your boss insists you use his language, tell him you can organise your thoughts better in your own language, or, if that does not work, allege linguistic discrimination and threaten to sue your employers for a vast sum.

Extended ASCII

Extended ASCII characters are perfectly valid as variable names, including ß, Ð, and ñ characters. They are almost impossible to type without copying/pasting in a simple text editor.

Names From Other Languages

Use foreign language dictionaries as a source for variable names. For example, use the German punkt for point. Maintenance coders, without your firm grasp of German, will enjoy the multicultural experience of deciphering the meaning.

Names From Mathematics

Choose variable names that masquerade as mathematical operators, e.g.:

openParen = (slash + asterix) / equals;

Bedazzling Names

Choose variable names with irrelevant emotional connotation. e.g.:

marypoppins = (superman + starship) / god;

This confuses the reader because they have difficulty disassociating the emotional connotations of the words from the logic they're trying to think about.

Rename and Reuse

This trick works especially well in Ada, a language immune to many of the standard obfuscation techniques. The people who originally named all the objects and packages you use were morons. Rather than try to convince them to change, just use renames and subtypes to rename everything to names of your own devising. Make sure to leave a few references to the old names in, as a trap for the unwary.

When To Use i

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

Conventions Schmentions

Ignore the Sun Java Coding Conventions, after all, Sun does. Fortunately, the compiler won't tattle when you violate them. The goal is to come up with names that differ subtly only in case. If you are forced to use the capitalisation conventions, you can still subvert wherever the choice is ambiguous, e.g. use both inputFilename and inputfileName. Invent your own hopelessly complex naming conventions, then berate everyone else for not following them.

Lower Case l Looks a Lot Like the Digit 1

Use lower case l to indicate long constants. e.g. 10l is more likely to be mistaken for 101 than 10L is. Ban any fonts that clearly disambiguate uvw, wW, gq9, 2z, 5s, il17|!j, oO08, `'", ;,., m nn rn, and {[()]}. Be creative.

Reuse of Global Names as Private

Declare a global array in module A, and a private one of the same name in the header file for module B, so that it appears that it's the global array you are using in module B, but it isn't. Make no reference in the comments to this duplication.

Recycling Revisited

Use scoping as confusingly as possible by recycling variable names in contradictory ways. For example, suppose you have global variables A and B, and functions foo and bar. If you know that variable A will be regularly passed to foo and B to bar, make sure to define the functions as function foo(B) and function bar(A) so that inside the functions A will always be referred to as B and vice versa. With more functions and globals, you can create vast confusing webs of mutually contradictory uses of the same names.

Recycle Your Variables

Wherever scope rules permit, reuse existing unrelated variable names. Similarly, use the same temporary variable for two unrelated purposes (purporting to save stack slots). For a fiendish variant, morph the variable, for example, assign a value to a variable at the top of a very long method, and then somewhere in the middle, change the meaning of the variable in a subtle way, such as converting it from a 0-based coordinate to a 1-based coordinate. Be certain not to document this change in meaning.

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. If you spell out names in full, there is only one possible way to spell each name. These are too easy for the maintenance programmer to remember. Because there are so many different ways to abbreviate a word, with abbreviations, you can have several different variables that all have the same apparent purpose. As an added bonus, the maintenance programmer might not even notice they are separate variables.

Misleading names

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.

m_

a naming convention from the world of C++ is the use of m_ in front of members. This is supposed to help you tell them apart from methods, so long as you forget that "method" also starts with the letter "m".

o_apple obj_apple

Use an "o" or "obj" prefix for each instance of the class to show that you're thinking of the big, polymorphic picture.

Hungarian Notation

Hungarian Notation is the tactical nuclear weapon of source