Code that cannot be maintained
Free translation with abbreviations of the first part of the essay "Unmaintainable Code". Variable naming is a rather banal topic (albeit funnyly stated), but without this part the essay would be incomplete.
This is the most popular of my essays. It's amazing how many people do not understand that this is a mockery.
')
This essay is written to create jobs for Java programmers. In it, I gathered the tips of the masters on how to write code that is so difficult to maintain that people who came after you would spend years making even minimal changes. Moreover, scrupulous adherence to these tips will provide you with employment until the end of life, since no one else has a chance to successfully support the code. However, if you followed all the rules, even you have no chance of that.
Do not overdo it: your code should not look unsupported, but only be so, otherwise it risks refactoring or just being rewritten.
Quidquid latine dictum sit, altum sonatur.
What is said in Latin sounds impressive.
In order to prevent a programmer who accompanies your code (hereafter “maintainer”), you must understand how he thinks. He has your huge code and has no time to read it all, not to mention understanding it. He wants to quickly find a place where he needs to change something, fix it and stop there, without getting unexpected side effects. He examines your code in parts, and your task is to ensure that he cannot get a general idea of ​​the code. Your goal is to make it as difficult as possible to find the code he needs, and most importantly, to ensure that he cannot ignore any code fragment.
Programmers entertain the illusions of agreements. Break the agreements a little - and the maintainer will have to read every line of your code with a magnifying glass. It may seem to you that any language property makes the code unsupported — not quite; only if used correctly.
“When I use the word,” said Humpty Dumpty contemptuously, “it means only what I mean — no more and no less.”
Much of the art of writing unsupported code is in naming variables and methods. They mean nothing to the compiler, and therefore provide you with unlimited possibilities to confuse the maintainer.
If you name your variables a, b, c, they will not be possible to search for them in a simple text editor. In addition, no one will guess what they are for. If someone mentions a violation of the tradition of calling the cycle counters i, j, and k, considered since FORTRAN, the 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 the cycle counters.
If you are forced to use descriptive names, make mistakes in them. Not all: an error in one name from a logical pair (for example, SetPintleOpening and SetPintalClosing) effectively neutralizes the use of grep or the search tools of the development environment. Add internationalization to taste: write tory or tori depending on 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 abbreviate code. Real machos never explain abbreviations: their understanding is in their blood. If you can't do it right away, quickly write code with meaningful names, and then automatically rename all variables and methods. If one concept can be abbreviated in several ways, use them all: it 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, one must assume, Ukrainianisms are recommended - comment. Per.) And slang spellings.
Scroll through the dictionary to find as many synonyms as possible for the same action (for example, display, show, present). Use them to indicate that there is a difference when in fact it is not. On the contrary, to name essentially different functions, use the same word (for example, print to mean “ink printing on paper”, “writing to a file” and “output to the screen”).
Under no circumstances agree to write a glossary containing unambiguous definitions of the terminology used in the project. Writing a glossary is a non-professional violation of the principle of structural design, known as “hiding information”.
If you are still forced to write a glossary, use recursive definitions. An example taken from Ant 1.6.5 manual: “basedir: the absolute path to the basedir project (specified in the basedir attribute of the project)”. The reader is still not clear what is basedir, although he may assume that this is the absolute path, despite the examples in which it begins with., That is, it is relative.
Tease your reader by pretending that you are giving information where there is none. Formulate your empty maxims so that the reader blames himself for not being able to extract something useful from them.
Never use illustrative examples, they are too clear. If you are forced 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 don’t want to teach, but to impress the reader, so that he will immediately get into all the possibilities of the program! People respect only that which is too abstract to be understood. In the end, not a single academician has yet been caught for giving examples.
Esperanto , Klingon and Westron are great . In pseudo-Esperanto, the plural is formed by adding oj. In this way you maintain world peace.
Arbitrarily translate the first letter of the syllable, as well as other letters, into uppercase.
In all cases permitted by the syntax of the language, let the classes, methods, member variables, parameters, global and local variables have the same name. It is advisable to reuse local variables inside {} blocks. This is done so that the maintainer carefully examines the scope of each variable. Depending on the language, the reuse possibilities vary, but it is almost always possible to find a way to insert a pleasant trifle into the code: passing variables A and B to the function, in the signature of the function, swap them; use one variable for different purposes or just slightly change its purpose.
If your development environment allows it, use accented letters in variable names. In many text editors such letters are difficult to distinguish from ordinary ones. A similar technique is the use of characters from the extended ASCII table, which makes it very difficult for a set of variable names.
If the compiler distinguishes only the first, say, 8 letters of a name, vary the endings, for example, var_unit_update () in one case and var_unit_setup () in another. The compiler will treat both names as var_unit.
Use _ and __ as variable names. In addition, adding a couple of underscores to the beginning and end of the variable name works well for getting new variables, preferably of a different type and purpose.
Randomly mix several languages ​​(human or computer). Human languages ​​can be used in comments and in the names of variables (form them from the English name of the entity or from Russian by transliteration). If your boss insists on using only one language, say that you are better able to express thoughts in another language. If this does not work, complain about 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 really have to use meaningful variable names, choose those whose meaning is strongly associated with something from a completely different domain. The names of mathematical symbols work well:
or names with strong emotional coloring:
Ignore the generally accepted conventions governing the appearance of the code, in particular, Sun's coding conventions and the Hungarian notation . Fortunately, the compiler does not respond to this. In addition, you can come up with your own agreements and blame everyone else for not using them.
In most fonts, there are pairs of characters with a similar pattern: l and 1, 0 and O, g and q, m and rn, etc. Use them! Exclude from use any fonts in which these characters are very different.
Make sure each method makes a little less or a little more than its name promises. For example, the isValid (x) method can have a side effect in the form of writing x to the database in binary form.
Instead of blue, name the constant 0x0204FB LancelotsFavoriteColour. This color looks just like normal blue, and the maintainer will have to suffer, figuring out the color code. Of course, only a person freely oriented in Monty Python and the Holy Grail will guess that Lancelot's favorite color is blue. On the other hand, if the 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 maintainers have already learned that hexadecimal codes are easily decoded, so decimal codes should be used. No normal person without a calculator decrypts 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.
In addition, you can play around with the renaming of colors: very few people know how puce, teal and papayawhip actually look, and this leaves room for reassigning color constants.
Remember that the human brain can comfortably process no more than 7 pieces of information at the same time? Use it. Create variable names that carry information of several orthogonal types (the type and scope of the variable, its origin and destination, and the date of creation). Give the program logic a complex nested structure; The optimal block size is slightly greater 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 do not understand that this is a mockery.
')
This essay is written to create jobs for Java programmers. In it, I gathered the tips of the masters on how to write code that is so difficult to maintain that people who came after you would spend years making even minimal changes. Moreover, scrupulous adherence to these tips will provide you with employment until the end of life, since no one else has a chance to successfully support the code. However, if you followed all the rules, even you have no chance of that.
Do not overdo it: your code should not look unsupported, but only be so, otherwise it risks refactoring or just being rewritten.
General principles
Quidquid latine dictum sit, altum sonatur.
What is said in Latin sounds impressive.
In order to prevent a programmer who accompanies your code (hereafter “maintainer”), you must understand how he thinks. He has your huge code and has no time to read it all, not to mention understanding it. He wants to quickly find a place where he needs to change something, fix it and stop there, without getting unexpected side effects. He examines your code in parts, and your task is to ensure that he cannot get a general idea of ​​the code. Your goal is to make it as difficult as possible to find the code he needs, and most importantly, to ensure that he cannot ignore any code fragment.
Programmers entertain the illusions of agreements. Break the agreements a little - and the maintainer will have to read every line of your code with a magnifying glass. It may seem to you that any language property makes the code unsupported — not quite; only if used correctly.
Naming
“When I use the word,” said Humpty Dumpty contemptuously, “it means only what I mean — no more and no less.”
Much of the art of writing unsupported code is in naming variables and methods. They mean nothing to the compiler, and therefore provide you with unlimited possibilities to confuse the maintainer.
1. Single letter variable names
If you name your variables a, b, c, they will not be possible to search for them in a simple text editor. In addition, no one will guess what they are for. If someone mentions a violation of the tradition of calling the cycle counters i, j, and k, considered since FORTRAN, the 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 the cycle counters.
2. Creative typos
If you are forced to use descriptive names, make mistakes in them. Not all: an error in one name from a logical pair (for example, SetPintleOpening and SetPintalClosing) effectively neutralizes the use of grep or the search tools of the development environment. Add internationalization to taste: write tory or tori depending on 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.NI.M. / prs skrschnnymi gzd intrsn
Use abbreviations to abbreviate code. Real machos never explain abbreviations: their understanding is in their blood. If you can't do it right away, quickly write code with meaningful names, and then automatically rename all variables and methods. If one concept can be abbreviated in several ways, use them all: it 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, one must assume, Ukrainianisms are recommended - comment. Per.) And slang spellings.
5. Synonyms
Scroll through the dictionary to find as many synonyms as possible for the same action (for example, display, show, present). Use them to indicate that there is a difference when in fact it is not. On the contrary, to name essentially different functions, use the same word (for example, print to mean “ink printing on paper”, “writing to a file” and “output to the screen”).
6. Avoid writing a project glossary.
Under no circumstances agree to write a glossary containing unambiguous definitions of the terminology used in the project. Writing a glossary is a non-professional violation of the principle of structural design, known as “hiding information”.
If you are still forced to write a glossary, use recursive definitions. An example taken from Ant 1.6.5 manual: “basedir: the absolute path to the basedir project (specified in the basedir attribute of the project)”. The reader is still not clear what is basedir, although he may assume that this is the absolute path, despite the examples in which it begins with., That is, it is relative.
Tease your reader by pretending that you are giving information where there is none. Formulate your empty maxims so that the reader blames himself for not being able to extract something useful from them.
Never use illustrative examples, they are too clear. If you are forced 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 don’t want to teach, but to impress the reader, so that he will immediately get into all the possibilities of the program! People respect only that which is too abstract to be understood. In the end, not a single academician has yet been caught for giving examples.
7. Plural by the rules of other languages
Esperanto , Klingon and Westron are great . In pseudo-Esperanto, the plural is formed by adding oj. In this way you maintain world peace.
8. WRITTEN REGISTRY
Arbitrarily translate the first letter of the syllable, as well as other letters, into uppercase.
9. Reuse of names
In all cases permitted by the syntax of the language, let the classes, methods, member variables, parameters, global and local variables have the same name. It is advisable to reuse local variables inside {} blocks. This is done so that the maintainer carefully examines the scope of each variable. Depending on the language, the reuse possibilities vary, but it is almost always possible to find a way to insert a pleasant trifle into the code: passing variables A and B to the function, in the signature of the function, swap them; use one variable for different purposes or just slightly change its purpose.
10. Accented Letters / Extended ASCII
If your development environment allows it, use accented letters in variable names. In many text editors such letters are difficult to distinguish from ordinary ones. A similar technique is the use of characters from the extended ASCII table, which makes it very difficult for a set of variable names.
11. Compiler name length restrictions
If the compiler distinguishes only the first, say, 8 letters of a name, vary the endings, for example, var_unit_update () in one case and var_unit_setup () in another. The compiler will treat both names as var_unit.
12. Underline - your friend
Use _ and __ as variable names. In addition, adding a couple of underscores to the beginning and end of the variable name works well for getting new variables, preferably of a different type and purpose.
13. The Tower of Babel
Randomly mix several languages ​​(human or computer). Human languages ​​can be used in comments and in the names of variables (form them from the English name of the entity or from Russian by transliteration). If your boss insists on using only one language, say that you are better able to express thoughts in another language. If this does not work, complain about 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. Meaningful variable names
If you really have to use meaningful variable names, choose those whose meaning is strongly associated with something from a completely different domain. The names of mathematical symbols work well:
openParen = ( slash + asterix ) / equals;or names with strong emotional coloring:
marypoppins = ( superman + starship ) / god;15. Say no to agreements.
Ignore the generally accepted conventions governing the appearance of the code, in particular, Sun's coding conventions and the Hungarian notation . Fortunately, the compiler does 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
In most fonts, there are pairs of characters with a similar pattern: l and 1, 0 and O, g and q, m and rn, etc. Use them! Exclude from use any fonts in which these characters are very different.
17. Confusing Method Names
Make sure each method makes a little less or a little more than its name promises. For example, the isValid (x) method can have a side effect in the form of writing x to the database in binary form.
18. Reference to the masterpieces of world culture
Instead of blue, name the constant 0x0204FB LancelotsFavoriteColour. This color looks just like normal blue, and the maintainer will have to suffer, figuring out the color code. Of course, only a person freely oriented in Monty Python and the Holy Grail will guess that Lancelot's favorite color is blue. On the other hand, if the 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 maintainers have already learned that hexadecimal codes are easily decoded, so decimal codes should be used. No normal person without a calculator decrypts 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.
In addition, you can play around with the renaming of colors: very few people know how puce, teal and papayawhip actually look, 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 the same time? Use it. Create variable names that carry information of several orthogonal types (the type and scope of the variable, its origin and destination, and the date of creation). Give the program logic a complex nested structure; The optimal block size is slightly greater than the number of lines that fit on the screen.
Source: https://habr.com/ru/post/99016/
All Articles