coding tips to memorize

September 1st, 2006

I stumbled upon the magnificent How To Write Unmaintainable Code by Roedy Green the other day and it really is something else. There are lots of humorous essays on bad coding, but this level of detail is so far unmatched in anything I've seen before. The whole this is pretty long, but here are some gems for you to savor...

Using 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.

Using names from mathematics...

Choose variable names that masquerade as mathematical operators, e.g.:
openParen = (slash + asterix) / equals;

Using downright creative 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.

Using 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.

Well, you get the idea... one last zinger for the road...

When implementing a very complicated algorithm, use the classic software engineering principles of doing a sound design before beginning coding. Write an extremely detailed design document that describes each step in a very complicated algorithm. The more detailed this document is, the better.

In fact, the design doc should break the algorithm down into a hierarchy of structured steps, described in a hierarchy of auto-numbered individual paragraphs in the document. Use headings at least 5 deep. Make sure that when you are done, you have broken the structure down so completely that there are over 500 such auto-numbered paragraphs. For example, one paragraph might be(this is a real example) - Display all impacts for activity where selected mitigations can apply (short pseudocode omitted).

then... (and this is the kicker) when you write the code, for each of these paragraphs you write a corresponding global function named:


Do not document these functions. After all, that's what the design document is for!

This entry basically adds nothing, but with the examples you've seen here you should now be eager to read the full story, it's worth it! :cool:

:: random entries in this category ::