Unmaintainable code
Unmaintainable code is an essay by Roedy Green about software development, software testing, code refactoring, and related topics.
Contents
- 1 Description
- 2 Topics
- 2.1 General Principles
- 2.2 Naming
- 2.3 Camouflage
- 2.4 Documentation
- 2.5 Program Design
- 2.6 Coding Obfuscation
- 2.7 Ambiguity
- 2.8 Testing
- 2.9 Choice of Language
- 2.10 Dealing With Others
- 2.11 Roll Your Own
- 2.12 Tricks In Offbeat Languages
- 2.13 Miscellaneous Techniques
- 2.14 Philosophy
- 2.15 The Shoemaker Has No Shoes
- 2.16 Contributors
- 2.17 Operation Termite
- 2.18 Feedback
- 3 See also
- 4 External links
Description
Unmaintainable code is a satire in the tradition of The Devil's Dictionary.
Many of the examples use Java, but the general principles apply to all programming languages.
See the official website for the complete essay.
Topics
Quotations are by Roedy Green, excerpt where stated otherwise.
General Principles
"You want to make it as hard as possible for [the maintenance programmer] 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."
Naming
"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."
See:
Camouflage
"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."
Documentation
"Since the computer ignores comments and documentation, you can lie outrageously and do everything in your power to befuddle the poor maintenance programmer."
Program Design
"The cardinal rule of writing unmaintainable code is to specify each fact in as many places as possible and in as many ways as possible."
Coding Obfuscation
"Sedulously eschew obfuscatory hyperverbosity and prolixity." (Anon.)
Ambiguity
"Use the fuzziest, vaguest most general terminology you can come up with, especially for variable names. handle is a great example — a handle to what? processData is a great method name. Was there ever a method written that could not be so described? It cleverly hides any clue to what it does behind a cloud of ambiguity.
"So, for example, when you mention the size of a display, make sure you make it abundantly unclear whether you mean to include the margins and/or the menu bar in the size. Mix both definitions in the same program using the same term for both."
Testing
"Leaving bugs in your programs gives the maintenance programmer who comes along later something interesting to do. A well done bug should leave absolutely no clue as to when it was introduced or where. The laziest way to accomplish this is simply never to test your code."
See:
Choice of Language
"Computer languages are gradually evolving to become more fool proof. Using state of the art languages is unmanly. Insist on using the oldest language you can get away with ..."
See:
Dealing With Others
"Hell is other people." (Jean-Paul Sartre)
Roll Your Own
"You’ve always wanted to write system level code. Now is your chance. Ignore the standard libraries and write your own. It will look great on your resumé."
Tricks In Offbeat Languages
"Programming in Basic causes brain damage." (Edsger Wybe Dijkstra)
Miscellaneous Techniques
"If you give someone a program, you will frustrate them for a day; if you teach them how to program, you will frustrate them for a lifetime." (Anon.)
Philosophy
"The people who design languages are the people who write the compilers and system classes. Quite naturally they design to make their work easy and mathematically elegant. However, there are 10,000 maintenance programmers to every compiler writer. The grunt maintenance programmers have absolutely no say in the design of languages. Yet the total amount of code they write dwarfs the code in the compilers.
"Maintenance programmers, if somebody ever consulted them, would demand ways to hide the housekeeping details so they could see the forest for the trees. They would demand all sorts of shortcuts so they would not have to type so much and so they could see more of the program at once on the screen. They would complain loudly about the myriad petty time-wasting tasks the compilers demand of them."
The Shoemaker Has No Shoes
(This one is serious, not satire.)
"Think of what might happen if we started storing source code as structured data. We could view the same source code in many alternate ways, e.g. as Java, as NextRex, as a decision table, as a flow chart, as a loop structure skeleton (with the detail stripped off), as Java with various levels of detail or comments removed, as Java with highlights on the variables and method invocations of current interest, or as Java with generated comments about argument names and/or types. We could display complex arithmetic expressions in 2D, the way TeX and mathematicians do. You could see code with additional or fewer parentheses, ( depending on how comfortable you feel with the precedence rules ). Parenthesis nests could use varying size and colour to help matching by eye. With changes as transparent overlay sets that you can optionally remove or apply, you could watch in real time as other programmers on your team, working in a different country, modified code in classes that you were working on too.
"You could use the full colour abilities of the modern screen to give subliminal clues, e.g. by automatically assigning a portion of the spectrum to each package/class using a pastel shades as the backgrounds to any references to methods or variables of that class. You could bold face the definition of any identifier to make it stand out.
"You could ask what methods/constructors will produce an object of type X? What methods will accept an object of type X as a parameter? What variables are accessible in this point in the code? By clicking on a method invocation or variable reference, you could see its definition, helping sort out which version of a given method will actually be invoked. You could ask to globally visit all references to a given method or variable, and tick them off once each was dealt with. You could do quite a bit of code writing by point and click.
"Some of these ideas would not pan out. But the best way to find out which would be valuable in practice is to try them. Once we had the basic tool, we could experiment with hundreds of similar ideas to make life easier for the maintenance programmer."
