After years of reading programming code, I have realised that there are a set of underground development standards that although not documented anywhere, are in widespread use. Based on all-too-real coding disasters, I have tried to write down these programming standards. Please do not try this at home!:
Make Your Code Unreadable!
The art of writing code in a way that makes it unreadable is a dying art. The current fashion for Janet and John code with subtitles for the hard of thinking is deskilling programming and generally giving the impression that communication capabilities are required attributes for programmers.
So Make Your Code Unreadable for these Reasons:
- Make Your Job More Fun! - You can use every ounce of your creativity to introduce new techniques in a haphazard fashion. No more regimentation!
- Make Others’ Jobs More Fun - A program can be like a crossword puzzle and a suduku all in one! Hours of fun for all the team!
Some Simple Techniques to Get You Started
Here is what needs to be entered on the typical program header:
- Author - Name your favourite Disney character
- Date - Should be left as the date of the template, not your program. If uncertain as to the date of the template, use 1066.
- Program Name - An opportunity to name one of your other masterpieces.
- Description - Describe, in 10 acronyms or less, what your program would like to be when it grows up.
- Version Number - Can be confusing to the novice and expert programmer alike. Leave the previous version number for continuity purposes.
See what interesting patterns you can create with the commenting character.
- Variable names should be 5 characters or less (preferably less).
- If using more characters, at least one character should be an ‘x’.
- ‘a’,’ b’ and ‘c’ are excellent standard variable names and can be used in most situations.
- Personalise your program by having a variable named after your dog.
- Most programs should have a variable ‘temp2’, even if ‘temp1’ has not been used.
- Recycle your variables for different tasks - save precious variable name resources.
- If you must use words in your variables, try to use the same words again and again in the variables - e.g. "LoopNum", "NumLoop", "LoopNo".
- Always remember - Abbreviate, Abbr, A!!!
- Booleans should simply be called "flag", declared as character or numeric, except, of course, when they are not.
- All variables can be global.
- Brackets should be liberally sprinkled across any serious expression. They add gravitas. Use double or triple brackets for additional emphasis. See just how many brackets you can get at the end of an expression. 18 is a good score.
- Always try to amalgamate expressions into one - don’t worry if they span a line or ten. If they do, reduce the length of the variable names and take out spaces.
- Do not waste memory and time with constants - just simply write in the numbers and literal text directly into your expressions.
- If True and False have numerical equivalents - use them (sometimes)!
- Use operator precedence - it was written into the language - so make use of it. If a programmer has forgotten if "or" comes before "and" - help them out by making them look it up.
- Provide an appreciation of the history of your program - leave the original comments undisturbed.
- Minimise clutter - do not add new comments when revising code - after all it can take a compiler microseconds to read them.
- Comments can look authoritative in all upper case - TRY IT OUT.
- Reference some mythical documentation that you won’t have time to write. You will be enhancing your colleagues search capabilities.
Comments can also be used to flesh out a short program. Be creative! Here are some suggestions:
- Add comments that state what each statement does. After all, the programmer reading the code may not know that "print a" writes the contents of variable a to the screen - you could be saving a trip to the language documentation.
- If you copy code from another program and need to delete some, just comment out the unnecessary code. Don’t worry if that leaves just one line in the middle - they’ll find it - eventually.
- Add some "personal flavour" - write in something about your day or a statement about the futility of the program.
- Why not add a quotation? Shakespeare, Simpsons or your favourite episode of Star Trek.
- Copy in the related emails as comments. What could be better documentation?
Procedures, Functions and Subroutines
- Naming - Use a singular noun where possible. Instead of "calculate_pension", just simple "pension" will do. Or even better, "pens" - people will appreciate your witty ambiguity.
- Leave in functions or procedures that are unused - archaeologists will love you. And after all, they may become useful in future!
- Bunch together unrelated tasks into a routine called "do-stuff". It will give them a sense of purpose.
- Functions and procedures do not need parameters. Problems with variable scope can be removed by simply using global variables.
I would like to crush a few myths:
- Loops can span pages.
- In most programming languages, loops can be exited from anywhere and as many times as you like.
Armed with this knowledge, there can be no end to your loops.
- Programs very rarely require parameters. The same effect can be achieved by simply editing your program.
- If you do decide to have parameters, always keep a spare, it may be needed later.
Errors, Exceptions and Education
- Do not waste your time determining the types of exception, most languages have a "catch-all" exception - so simplify your code and use it.
- Users can spend valuable time examining error logs - save their time by not writing to it.
- If you do need to write to the error log, keep disk usage to minimum with extreme brevity.
- If you are going to provide an error message to a user, make it dramatic - "fatal" implies someone died, "lethal" implies someone is about to die.
- Describe your error message in terms a professional programmer will understand.
- Do not try to tell the user how to do their job - describe what has occurred, not what you think they should do next.
- Be precise and generic. Simply saying the program could not read the input file does not provide enough information - actually your program received a non-zero error code from an operating system call. This error can then be used for any system call provided, of course, you do not give the error code or filename.
- If an error is due to misguided user input, then the user has not received training on the program’s use. Do not allow uneducated users make dangerous mistakes with your program, do not even hint the issue is to do with their input, otherwise they may "guess" how to put it right!
See these guidelines applied in Make Your Code Unreadable! Case Study