How to document code

[Sasaki Kojiro]

Funny if you've ever done any programming.

"In the interests of creating employment opportunities in the Java programming field, I am passing on these tips from the masters on how to write code that is so difficult to maintain, that the people who come after you will take years to make even the simplest changes. Further, if you follow all these rules religiously, you will even guarantee yourself a lifetime of employment, since no one but you has a hope in hell of maintaining the code. Then again, if you followed all these rules religiously, even you wouldn't be able to maintain the code!"

Some choice bits:

#
Bedazzling 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.

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.

Obscure film references
: Use constant names like LancelotsFavouriteColour instead of blue and assign it hex value of 0x0204FB. The color looks identical to pure blue on the screen, and a maintenance programmer would have to work out 0204FB (or use some graphic tool) to know what it looks like. Only someone intimately familiar with Monty Python and the Holy Grail would know that Lancelot's favorite color was blue. If a maintenance programmer can't quote entire Monty Python movies from memory, he or she has no business being a programmer.

Oh, and on a semi-related note, Microsoft has released a new mini keyboard featuring only the most commonly used keys:

[Big King Sanctaphrax]

If a maintenance programmer can't quote entire Monty Python movies from memory, he or she has no business being a programmer.

Truer words have never been spoken.

[SwordsMaster]

LOL

I friend of mine declares variables with random people's names. Say a counter for a loop in a search program could be called "jimmy" or bob. Its weird seeing expressions like jimmy = jimmy +1;

The guy actually talks to his variables in really long programming sequences.

[Sasaki Kojiro]

Whoops, I forgot the link: http://mindprod.com/unmain.html

[Kraellin]

lol. not being a true programmer, i only get most of the jokes there, but i love the keyboard pic :)

K.

[Ronin]

Murphy's computers laws

* Any given program, when running, is obsolete.
* Any given program costs more and takes longer each time it is run.
* If a program is useful, it will have to be changed.
* If a program is useless, it will have to be documented----->the most universal truth EVER!!!!


get the full list here

[Togakure]

Yes this is usually funny. Unfortunately, there are programmers that actual do this, albeit in a much more subtle way than suggested in this humorous example.

Picture this:

A government software development project has taken 200% longer and has cost 500% more than it was originally intended to (nearing 1 million of your state tax payer dollars--ARGH THAT ALWAYS PISSES ME OFF!!). The cause was, the team split in two politically (because the Lead was having an affair with a married/kids programmer and the other two found out about it and were the ethical types). The IT Branch Chief is fed up with the excuses and has reassigned all of them, and because of your recent success and obvious ambition, has given you the Lead to make something out of the mess--with one other (talented) staff. You examine the system to find the above-described "technique" has been applied on all fronts, you have 6 months, and the Chief has made it clear that he doesn't want excuses, just results ... .

Still funny? Yeah, but it wouldn't be if you were in the hot seat. I was in this exact position before.

The code was unsalvageable, even if we had a year to unravel the mess. But, the system was a standard accounting system, with the same process automated by every state department out there. My solution? Why reinvent the wheel? Why the hell was the decision made to develop a "new" system in the first place? The major COSTLY error was made long before the first line of code was written, and not by the developers ... (c'est classique, but I was certainly not going to point the finger at the Chief!).

We ignored the spaghetti system and quickly found a system in another department that met our users' requirements. This system just happened to run on a recently retired platform that was taking up space in our mothball storage (a dinosaur Unix Sytem 6 mini-computer and office automation terminals; big stroke of luck there). The other department's staff were extremely friendly and willing to help (even on her own time; Carla was so cool). We took the system code from her department (state developed, so public domain and no cost), brought up the old Unix platform (virtually no platform costs), installed the system, made modest edits to accommodate slightly different business processes, and had it up and running in (just barely) 6 months. The users were ecstatic, the Branch Chief rather amazed, and me and my buddy got promos out of the deal--and yummy boxes of chocolates from our customers too.

Hope any programmers who encounter a situation like this in their careers are as lucky as we were!