How To Write Unmaintainable Code
Ensure a job for life ;-)
Roedy Green
Canadian Mind Products
--------------------------------------------------------------------------------
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. By 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 adsf 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 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. 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 subtlely only in case. If you are
forced to use the capitalisation conventions, you can still subvert
wherever the choice is ambigous, 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 that 10L is. Ban any fonts that clearly
disambiguate uvw wW gq9 2z 5s il17|!j oO08 `'" ;,. m nn rn {[()]}. 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 code
obfuscation techniques; use it! Due to the sheer volume of source code
contaminated by this idiom nothing can kill a maintenance engineer
faster than a well planned Hungarian Notation attack. The following
tips will help you corrupt the original intent of Hungarian Notation:
Insist on using "c" for const in C++ and other languages that directly
enforce the const-ness of a variable.
Seek out and use Hungarian warts that have meaning in languages other
than your current language. For example insist on the PowerBuilder
"l_" and "a_ " {local and argument} scoping prefixes and always use
the VB-esque style of having a Hungarian wart for every control type
when coding to C++. Try to stay ignorant of the fact that megs of
plainly visible MFC source code does not use Hungarian warts for
control types.
Always violate the Hungarian principle that the most commonly used
variables should carry the least extra information around with them.
Achieve this end through the techniques outlined above and by
insisting that each class type have a custom wart prefix. Never allow
anyone to remind you that no wart tells you that something is a class.
The importance of this rule cannot be overstated if you fail to adhere
to its principles the source code may become flooded with shorter
variable names that have a higher vowel/consonant ratio. In the worst
case scenario this can lead to a full collapse of obfuscation and the
spontaneous reappearance of English Notation in code!
Flagrantly violate the Hungarian-esque concept that function
parameters and other high visibility symbols must be given meaningful
names, but that Hungarian type warts all by themselves make excellent
temporary variable names.
Insist on carrying outright orthogonal information in your Hungarian
warts. Consider this real world example "a_crszkvc30LastNameCol". It
took a team of maintenance engineers nearly 3 days to figure out that
this whopper variable name described a const, reference, function
argument that was holding information from a database column of type
Varchar[30] named "LastName" which was part of the table's primary
key. When properly combined with the principle that "all variables
should be public" this technique has the power to render thousands of
lines of source code obsolete instantly!
Use to your advantage the principle that the human brain can only hold
7 pieces of information concurrently. For example code written to the
above standard has the following properties:
a single assignment statement carries 14 pieces of type and name information.
a single function call that passes three parameters and assigns a
result carries 29 pieces of type and name information.
Seek to improve this excellent, but far too concise, standard. Impress
management and coworkers by recommending a 5 letter day of the week
prefix to help isolate code written on 'Monam' and 'FriPM'.
It is easy to overwhelm the short term memory with even a moderately
complex nesting structure, especially when the maintenance programmer
can't see the start and end of each block on screen simultaneously.
Hungarian Notation Revisited
One followon trick in the Hungarian notation is "change the type of a
variable but leave the variable name unchanged". This is almost
invariably done in windows apps with the migration from Win16 :-
WndProc(HWND hW, WORD wMsg, WORD wParam, LONG lParam) to Win32
WndProc(HWND hW, UINT wMsg, WPARAM wParam, LPARAM lParam) where the w
values hint that they are words, but they really refer to longs. The
real value of this approach comes clear with the Win64 migration, when
the parameters will be 64 bits wide, but the old "w" and "l" prefixes
will remain forever.
Reduce, Reuse, Recycle
If you have to define a structure to hold data for callbacks, always
call the structure PRIVDATA. Every module can define it's own
PRIVDATA. In VC++, this has the advantage of confusing the debugger so
that if you have a PRIVDATA variable and try to expand it in the watch
window, it doesn't know which PRIVDATA you mean, so it just picks one.
Obscure film references
Use constant names like LancelotsFavouriteColour instead of blue and
assign it hex value of $0204FB. The color looks identical to pure blue
on the screen, and a maintenance programmer would have to work out
0204FB (or use some graphic tool) to know what it looks like. Only
someone intimately familiar with Monty Python and the Holy Grail would
know that Lancelot's favorite color was blue. If a maintenance
programmer can't quote entire Monty Python movies from memory, he or
she has no business being a programmer.
Camouflage
The longer it takes for a bug to surface, the harder it is to find.
- Roedy Green
Much of the skill in writing unmaintainable code is the art of
camouflage, hiding things, or making things appear to be what they are
not. Many depend on the fact the compiler is more capable at making
fine distinctions than either the human eye or the text editor. Here
are some of the best camouflaging techniques.
Code That Masquerades As Comments and Vice Versa
Include sections of code that is commented out but at first glance
does not appear to be.
for(j=0; j<array_len; j+ =8)
{
total += array[j+0 ];
total += array[j+1 ];
total += array[j+2 ]; /* Main body of
total += array[j+3]; * loop is unrolled
total += array[j+4]; * for greater speed.
total += array[j+5]; */
total += array[j+6 ];
total += array[j+7 ];
}
Without the colour coding would you notice that three lines of code
are commented out?
namespaces
Struct/union and typedef struct/union are different name spaces in C
(not in C++). Use the same name in both name spaces for structures or
unions. Make them, if possible, nearly compatible.
typedef struct {
char* pTr;
size_t lEn;
} snafu;
struct snafu {
unsigned cNt
char* pTr;
size_t lEn;
} A;
Hide Macro Definitions
Hide macro definitions in amongst rubbish comments. The programmer
will get bored and not finish reading the comments thus never discover
the macro. Ensure that the macro replaces what looks like a perfectly
legitimate assignment with some bizarre operation, a simple example:
#define a=b a=0-b
Look Busy
use define statements to make made up functions that simply comment
out their arguments, e.g.:
#define fastcopy(x,y,z) /*xyz*/
...
fastcopy(array1, array2, size); /* does nothing */
Use Continuation to hide variables
Instead of using
#define local_var xy_z
break up "xy_z" onto two lines:
#define local_var xy\
_z // local_var OK
That way a global search for xy_z will come up with nothing for that
file. To the C preprocessor, the "\" at the end of the line means glue
this line to the next one.
Arbitrary Names That Masquerade as Keywords
When documenting, and you need an arbitrary name to represent a
filename use "file ". Never use an obviously arbitrary name like
"Charlie.dat" or "Frodo.txt". In general, in your examples, use
arbitrary names that sound as much like reserved keywords as possible.
For example, good names for parameters or variables would be"bank",
"blank", "class", "const ", "constant", "input", "key", "keyword",
"kind", "output", "parameter" "parm", "system", "type", "value", "var"
and "variable ". If you use actual reserved words for your arbitrary
names, which would be rejected by your command processor or compiler,
so much the better. If you do this well, the users will be hopelessly
confused between reserved keywords and arbitrary names in your
example, but you can look innocent, claiming you did it to help them
associate the appropriate purpose with each variable.
Code Names Must Not Match Screen Names
Choose your variable names to have absolutely no relation to the
labels used when such variables are displayed on the screen. E.g. on
the screen label the field "Postal Code" but in the code call the
associated variable "zip".
Don't Change Names
Instead of globally renaming to bring two sections of code into sync,
use multiple TYPEDEFs of the same symbol.
How to Hide Forbidden Globals
Since global variables are "evil", define a structure to hold all the
things you'd put in globals. Call it something clever like
EverythingYoullEverNeed. Make all functions take a pointer to this
structure (call it handle to confuse things more). This gives the
impression that you're not using global variables, you're accessing
everything through a "handle". Then declare one statically so that all
the code is using the same copy anyway.
Hide Instances With Synonyms
Maintenance programmers, in order to see if they'll be any cascading
effects to a change they make, do a global search for the variables
named. This can be defeated by this simple expedient of having
synonyms, such as
#define xxx global_var // in file std.h
#define xy_z xxx // in file ..\other\substd.h
#define local_var xy_z // in file ..\codestd\inst.h
These defs should be scattered through different include-files. They
are especially effective if the include-files are located in different
directories. The other technique is to reuse a name in every scope.
The compiler can tell them apart, but a simple minded text searcher
cannot. Unfortunately SCIDs in the coming decade will make this simple
technique impossible. since the editor understands the scope rules
just as well as the compiler.
Long Similar Variable Names
Use very long variable names or class names that differ from each
other by only one character, or only in upper/lower case. 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. l is an
exceptionally fine choice for a variable name since it will, to the
casual glance, masquerade as the constant 1. In many fonts rn looks
like an m. So how about a variable swirnrner. Create variable names
that differ from each other only in case e.g. HashTable and Hashtable.
Similar-Sounding Similar-Looking Variable Names
Although we have one variable named xy_z, there's certainly no reason
not to have many other variables with similar names, such as xy_Z,
xy__z, _xy_z, _xyz, XY_Z, xY_z, and Xy_z.
Variables that resemble others except for capitalization and
underlines have the advantage of confounding those who like
remembering names by sound or letter-spelling, rather than by exact
representations.
Overload and Bewilder
In C++, overload library functions by using #define. That way it looks
like you are using a familiar library function where in actuality you
are using something totally different.
Choosing The Best Overload Operator
In C++, overload +,-,*,/ to do things totally unrelated to addition,
subtraction etc. After all, if the Stroustroup can use the shift
operator to do I/O, why should you not be equally creative? If you
overload +, make sure you do it in a way that i = i + 5; has a totally
different meaning from i += 5; Here is an example of elevating
overloading operator obfuscation to a high art. Overload the '!'
operator for a class, but have the overload have nothing to do with
inverting or negating. Make it return an integer. Then, in order to
get a logical value for it, you must use '! !'. However, this inverts
the logic, so [drum roll] you must use '! ! !'. Don't confuse the !
operator, which returns a boolean 0 or 1, with the ~ bitwise logical
negation operator.
Overload new
Overload the "new" operator - much more dangerous than overloading the
+-/*. This can cause total havoc if overloaded to do something
different from it's original function (but vital to the object's
function so it's very difficult to change). This should ensure users
trying to create a dynamic instance get really stumped. You can
combine this with the case sensitivity trickalso have a member
function, and variable called "New".
#define
#define in C++ deserves an entire essay on its own to explore its rich
possibilities for obfuscation. Use lower case #define variables so
they masquerade as ordinary variables. Never use parameters to your
preprocessor functions. Do everything with global #defines. One of the
most imaginative uses of the preprocessor I have heard of was
requiring five passes through CPP before the code was ready to
compile. Through clever use of defines and ifdefs, a master of
obfuscation can make header files declare different things depending
on how many times they are included. This becomes especially
interesting when one header is included in another header. Here is a
particularly devious example:
#ifndef DONE
#ifdef TWICE
// put stuff here to declare 3rd time around
void g(char* str);
#define DONE
#else // TWICE
#ifdef ONCE
// put stuff here to declare 2nd time around
void g(void* str);
#define TWICE
#else // ONCE
// put stuff here to declare 1st time around
void g(std::string str);
#define ONCE
No comments:
Post a Comment