July 13, 2010 at 17:50Code That Cannot Be Supported
- Transfer
Free translation with abbreviations of the first part of the essay "Unmaintainable Code". Naming variables is a pretty commonplace topic (albeit amusingly stated), but without this part the essay would be incomplete.
This is the most popular of my essays. It's amazing how many people don’t understand that this is a mockery.
This essay is written to create jobs for Java programmers. In it, I gathered the advice of masters on how to write code that is so difficult to maintain that people who come after you will spend years making even minimal changes. Moreover, careful adherence to these tips will provide you with employment until the end of your life, since no one else has a chance to successfully support the code. However, if you followed all the rules, even you don't have a chance.
Do not overdo it: your code should not look unsupported, but just be that way, otherwise it runs the risk of being refactored or just being rewritten.
Quidquid latine dictum sit, altum sonatur.
What is said in Latin sounds impressive.
To prevent the programmer who accompanies your code (hereinafter “the maintainer”), you must understand how he thinks. It has your huge code and no time to read it all, not to mention to understand it. He wants to quickly find a place where you need to change something, fix it and stop there, without receiving unexpected side effects. It examines your code in parts, and your task is to ensure that it cannot compose a general idea of the code. Your goal is to complicate the search for the code he needs as much as possible, and most importantly, to ensure that he cannot ignore a single piece of code.
Programmers amuse themselves with the illusions of conventions. Break the conventions slightly - and the maintainer will have to read every line of your code with a magnifying glass. It may seem to you that any property of the language makes the code unsupported - not really; only if used correctly.
“When I use the word,” Humpty Dumpty said contemptuously, “it means only what I mean - nothing more and nothing less.”
A significant part of the art of writing unsupported code is naming variables and methods. They mean nothing to the compiler, and therefore provide you with unlimited possibilities for confusing the maintainer.
If you name your variables a, b, c, it will be impossible to find them in a simple text editor. In addition, no one will guess what they are for. If anyone mentions a violation of the tradition of calling cycle counts i, j and k, honored since FORTRAN, a method of replacing them with ii, jj and kk, mention what the Spanish Inquisition did with heretics. Instead, use the names i, j, and k for anything but loop counters.
If you are forced to use descriptive names, make mistakes in them. Not all: an error in a single name from a logical pair (for example, SetPintleOpening and SetPintalClosing) effectively neutralizes the use of grep or search tools of the development environment. Add internationalization to your taste: write tory or tori depending on the localization.
Use abstract words and concepts (it, everything, data, handle, stuff, do, routine, perform), as well as numbers: routineX48, PerformDataFunction, DoIt, HandleStuff and do_args_method.
Use abbreviations to shorten code. Real machos never explain abbreviations: their understanding is in their blood. If you cannot do this right away, quickly write code with meaningful names, and then automatically rename all the variables and methods. If one concept can be reduced in several ways, use all of them: this will help in the fight against those lazy people who are trying to comprehend your program with a simple text search. Use also Americanisms (for our locale, presumably, Ukrainisms are recommended - approx. Per.) And slang spellings.
Scroll through the dictionary for as many synonyms as possible for the same action (e.g. display, show, present). Use them to indicate that there is a difference when it really is not. On the contrary, to name essentially different functions, use the same word (for example, print to mean “print with ink on paper”, “write to file” and “output to screen”).
Under no circumstances do you agree to write a glossary containing unambiguous definitions of the terminology used in the project. Writing a glossary is an unprofessional violation of the principle of structural design, known as “information hiding”.
If you still have to write a glossary, use recursive definitions. An example taken from the Ant 1.6.5 manual: “basedir: the absolute path to the project's basedir (specified in the project’s basedir attribute).” The reader still does not understand what basedir is, although he can assume that this is the absolute path, despite the examples in which he begins with., That is, is relative.
Tease your reader by pretending to give information where it is not. Formulate your empty maxims so that the reader blames himself for not being able to extract something useful from them.
Never use visual examples, they are too clear. If you have to use them, complain that they look childish and unprofessional, in addition, it seems that these examples are all that the product can do. But you do not want to teach, but impress the reader, so that he immediately imbued with all the features of the program! People respect only that which is too abstract to be understood. In the end, not a single academician has been caught giving examples.
Perfect Esperanto , Klingon language and Westron . In pseudo Esperanto, the plural is formed by adding oj. In this way, you maintain world peace.
Arbitraryly capitalize the first letter of the syllable, as well as other letters.
In all cases allowed by the language syntax, give the classes, methods, member variables, parameters, global and local variables the same names. It is advisable to reuse local variables inside the {} blocks. This is done so that the attendant carefully examined the scope of each variable. Depending on the language, the possibilities of reuse vary, but you can almost always find a way to insert a pleasant trifle into the code: passing variables A and B to the function, in the function signature change their places; use one variable for different purposes or just slightly change its purpose.
If your development environment allows this, use accented letters in variable names. In many text editors, such letters are difficult to distinguish from ordinary letters. A similar trick is to use characters from the extended ASCII table, which greatly complicates the set of variable names.
If the compiler distinguishes only the first, say, 8 letters of the name, vary the endings, for example, var_unit_update () in one case and var_unit_setup () in the other. The compiler will treat both names as var_unit.
Use _ and __ as variable names. In addition, adding a couple or three underscores to the beginning and to the end of a variable name works well to get new variables, preferably of a different type and purpose.
Randomly mix multiple languages (human or computer). Human languages can be used in comments and in variable names (form them from the English name of the entity or from Russian translit). If your boss insists on using only one language, say that you are better at expressing thoughts in another language. If this does not help, complain of linguistic discrimination and threaten to sue. If you know too few languages, you can always borrow a few words from the dictionary for variable names.
If you have to use meaningful variable names, choose those whose value is strongly associated with something from a completely different subject area. The names of mathematical symbols work well:
or names with a strong emotional coloring:
Ignore generally accepted conventions that govern the appearance of code, in particular, Sun's coding conventions and Hungarian notation . Fortunately, the compiler will not respond to this. In addition, you can come up with your own agreements and blame everyone else for not using them.
Most fonts have pairs of characters that have a similar style: l and 1, 0 and O, g and q, m and rn, etc. Use them! Eliminate from use any fonts in which these characters are very different.
Make sure that each method does a little less or a little more than its name promises. For example, the isValid (x) method can have a side effect of writing x to the database in binary form.
Instead of blue, name the constant 0x0204FB LancelotsFavouriteColour. This color looks exactly like regular blue, and the maintainer will have to torment, figuring out the color code. Of course, only a person who is fluent in Monty Python and the Holy Grail will guess that Lancelot's favorite color is blue. On the other hand, if an maintainer is not even able to quote Monty Python movies from memory, what does he do in programming?
It goes without saying that instead of color names, their numerical values should be used. Unfortunately, most of the companions have already learned that hexadecimal codes are easily decrypted, so decimal codes should be used. No normal person without a calculator will decrypt 132347 as blue. Ideally, you need to select colors whose decimal notation is a hexadecimal notation of some other colors. So, for example, 808000 is actually 0x0c5440.
You can also play around with renaming colors: very few people know what puce, teal and papayawhip really look like, and this leaves room for reassigning color constants.
Remember that the human brain can comfortably process no more than 7 pieces of information at a time? Use this. Create variable names that carry information of several orthogonal types (type and scope of a variable, its origin and destination, as well as the creation date). Give the logic of the program the appearance of a complex nested structure; the optimal block size is slightly larger than the number of lines that fit on the screen.
Prologue
This is the most popular of my essays. It's amazing how many people don’t understand that this is a mockery.
This essay is written to create jobs for Java programmers. In it, I gathered the advice of masters on how to write code that is so difficult to maintain that people who come after you will spend years making even minimal changes. Moreover, careful adherence to these tips will provide you with employment until the end of your life, since no one else has a chance to successfully support the code. However, if you followed all the rules, even you don't have a chance.
Do not overdo it: your code should not look unsupported, but just be that way, otherwise it runs the risk of being refactored or just being rewritten.
General principles
Quidquid latine dictum sit, altum sonatur.
What is said in Latin sounds impressive.
To prevent the programmer who accompanies your code (hereinafter “the maintainer”), you must understand how he thinks. It has your huge code and no time to read it all, not to mention to understand it. He wants to quickly find a place where you need to change something, fix it and stop there, without receiving unexpected side effects. It examines your code in parts, and your task is to ensure that it cannot compose a general idea of the code. Your goal is to complicate the search for the code he needs as much as possible, and most importantly, to ensure that he cannot ignore a single piece of code.
Programmers amuse themselves with the illusions of conventions. Break the conventions slightly - and the maintainer will have to read every line of your code with a magnifying glass. It may seem to you that any property of the language makes the code unsupported - not really; only if used correctly.
Naming
“When I use the word,” Humpty Dumpty said contemptuously, “it means only what I mean - nothing more and nothing less.”
A significant part of the art of writing unsupported code is naming variables and methods. They mean nothing to the compiler, and therefore provide you with unlimited possibilities for confusing the maintainer.
1. Single-letter variable names
If you name your variables a, b, c, it will be impossible to find them in a simple text editor. In addition, no one will guess what they are for. If anyone mentions a violation of the tradition of calling cycle counts i, j and k, honored since FORTRAN, a method of replacing them with ii, jj and kk, mention what the Spanish Inquisition did with heretics. Instead, use the names i, j, and k for anything but loop counters.
2. Creative typos
If you are forced to use descriptive names, make mistakes in them. Not all: an error in a single name from a logical pair (for example, SetPintleOpening and SetPintalClosing) effectively neutralizes the use of grep or search tools of the development environment. Add internationalization to your taste: write tory or tori depending on the localization.
3. Be abstract
Use abstract words and concepts (it, everything, data, handle, stuff, do, routine, perform), as well as numbers: routineX48, PerformDataFunction, DoIt, HandleStuff and do_args_method.
4. A.K.R.O.N.I.M. / pst skrshnmi GRZD intrsn
Use abbreviations to shorten code. Real machos never explain abbreviations: their understanding is in their blood. If you cannot do this right away, quickly write code with meaningful names, and then automatically rename all the variables and methods. If one concept can be reduced in several ways, use all of them: this will help in the fight against those lazy people who are trying to comprehend your program with a simple text search. Use also Americanisms (for our locale, presumably, Ukrainisms are recommended - approx. Per.) And slang spellings.
5. Synonyms
Scroll through the dictionary for as many synonyms as possible for the same action (e.g. display, show, present). Use them to indicate that there is a difference when it really is not. On the contrary, to name essentially different functions, use the same word (for example, print to mean “print with ink on paper”, “write to file” and “output to screen”).
6. Avoid writing a project glossary
Under no circumstances do you agree to write a glossary containing unambiguous definitions of the terminology used in the project. Writing a glossary is an unprofessional violation of the principle of structural design, known as “information hiding”.
If you still have to write a glossary, use recursive definitions. An example taken from the Ant 1.6.5 manual: “basedir: the absolute path to the project's basedir (specified in the project’s basedir attribute).” The reader still does not understand what basedir is, although he can assume that this is the absolute path, despite the examples in which he begins with., That is, is relative.
Tease your reader by pretending to give information where it is not. Formulate your empty maxims so that the reader blames himself for not being able to extract something useful from them.
Never use visual examples, they are too clear. If you have to use them, complain that they look childish and unprofessional, in addition, it seems that these examples are all that the product can do. But you do not want to teach, but impress the reader, so that he immediately imbued with all the features of the program! People respect only that which is too abstract to be understood. In the end, not a single academician has been caught giving examples.
7. Plural according to the rules of other languages
Perfect Esperanto , Klingon language and Westron . In pseudo Esperanto, the plural is formed by adding oj. In this way, you maintain world peace.
8. TOP REGISTRY
Arbitraryly capitalize the first letter of the syllable, as well as other letters.
9. Reuse of names
In all cases allowed by the language syntax, give the classes, methods, member variables, parameters, global and local variables the same names. It is advisable to reuse local variables inside the {} blocks. This is done so that the attendant carefully examined the scope of each variable. Depending on the language, the possibilities of reuse vary, but you can almost always find a way to insert a pleasant trifle into the code: passing variables A and B to the function, in the function signature change their places; use one variable for different purposes or just slightly change its purpose.
10. Accented Letters / Advanced ASCII
If your development environment allows this, use accented letters in variable names. In many text editors, such letters are difficult to distinguish from ordinary letters. A similar trick is to use characters from the extended ASCII table, which greatly complicates the set of variable names.
11. Compiler Name Length Limitations
If the compiler distinguishes only the first, say, 8 letters of the name, vary the endings, for example, var_unit_update () in one case and var_unit_setup () in the other. The compiler will treat both names as var_unit.
12. Underline is your friend
Use _ and __ as variable names. In addition, adding a couple or three underscores to the beginning and to the end of a variable name works well to get new variables, preferably of a different type and purpose.
13. Tower of Babel
Randomly mix multiple languages (human or computer). Human languages can be used in comments and in variable names (form them from the English name of the entity or from Russian translit). If your boss insists on using only one language, say that you are better at expressing thoughts in another language. If this does not help, complain of linguistic discrimination and threaten to sue. If you know too few languages, you can always borrow a few words from the dictionary for variable names.
14. Significant variable names
If you have to use meaningful variable names, choose those whose value is strongly associated with something from a completely different subject area. The names of mathematical symbols work well:
openParen = ( slash + asterix ) / equals;or names with a strong emotional coloring:
marypoppins = ( superman + starship ) / god;15. Say no to agreements
Ignore generally accepted conventions that govern the appearance of code, in particular, Sun's coding conventions and Hungarian notation . Fortunately, the compiler will not respond to this. In addition, you can come up with your own agreements and blame everyone else for not using them.
16. Similar characters
Most fonts have pairs of characters that have a similar style: l and 1, 0 and O, g and q, m and rn, etc. Use them! Eliminate from use any fonts in which these characters are very different.
17. Confusing Method Names
Make sure that each method does a little less or a little more than its name promises. For example, the isValid (x) method can have a side effect of writing x to the database in binary form.
18. References to the masterpieces of world culture
Instead of blue, name the constant 0x0204FB LancelotsFavouriteColour. This color looks exactly like regular blue, and the maintainer will have to torment, figuring out the color code. Of course, only a person who is fluent in Monty Python and the Holy Grail will guess that Lancelot's favorite color is blue. On the other hand, if an maintainer is not even able to quote Monty Python movies from memory, what does he do in programming?
19. Color entertainment
It goes without saying that instead of color names, their numerical values should be used. Unfortunately, most of the companions have already learned that hexadecimal codes are easily decrypted, so decimal codes should be used. No normal person without a calculator will decrypt 132347 as blue. Ideally, you need to select colors whose decimal notation is a hexadecimal notation of some other colors. So, for example, 808000 is actually 0x0c5440.
You can also play around with renaming colors: very few people know what puce, teal and papayawhip really look like, and this leaves room for reassigning color constants.
20. Achievements of advanced psychology
Remember that the human brain can comfortably process no more than 7 pieces of information at a time? Use this. Create variable names that carry information of several orthogonal types (type and scope of a variable, its origin and destination, as well as the creation date). Give the logic of the program the appearance of a complex nested structure; the optimal block size is slightly larger than the number of lines that fit on the screen.