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!

[Sasaki Kojiro]

Ouch...that's bad. I guess I see why my teacher makes documentation 60% percent of our grade now.

[Gregoshi]

SK, the reality is that unless you work for a very disciplined leader/supervisor/manager, documentation will be the first thing sacrificed when the project inevitably falls behind schedule.


There was a pet phrase where I used to work: "I never saw a line of code I didn't want to re-write." With programming, much like driving a car, only you have a clue how to do it best.

Another good line I'd hear every now and then: "The code is self-documenting." Yeah, right.

[Togakure]

... "The code is self-documenting." Yeah, right.

Lol, yes indeed. That one's classic.

Generally speaking, public sector software development is a bit different that private. The software life cycle in the private industry is often much shorter (overall life cycle, not development life cycle). We had huge critical systems coded in COBOL that were originally developed in the early 70s, still in production in the late 90s (all of California's unemployment check processing, for example). Because of the multitude of costly nightmares arising from a lack of documentation of such systems, the public sector--at least where I worked--is pretty strict about documentation. In private industry though, say for developing games and such, deadline is everything, and as the code won't usually be maintained for much more than 2-4 years, I can see why documentation would not be a very high priority in a crunch (much to the dismay of any maintenance or evolutionary programmers later on ...).

A few annoying programmers (new systems developers) have this attitude: well, I'm not going to be around to have to maintain it so what do I care? I found this to be really annoying (so I made their lazy arses polish the documentation with a toothbrush). The overall cost of a system escalates considerably over its life cycle when it takes days instead of hours, or weeks instead of days, to make a minor processing change to an existing system (e.g. legislation changes laws and processes constantly, necessitating frequent changes in the systems that support those laws and processes). When you take into account all of the regression testing that must take place (dependencies on and obligations to other systems, etc.), good documentation is really, really important. In the long run (in public sector work) missing the deadline is far less costly to the taxpayer than shortchanging the documentation. Of course, the REAL issue is--missing the deadline doesn't make the politicians in charge look good and that's what really drives the wagon--right into the mud, often enough.

Gah ... nasty flashbacks. Why am I even talking about this? Time for bed ... .

[Gregoshi]

Of course, the REAL issue is--missing the deadline doesn't make the politicians in charge look good and that's what really drives the wagon--right into the mud, often enough.

Ah, memories. I remember the reaction of one of my friends when he was given a new software development project. He put together a beautifully detailed project plan that had the project completed in 6 months. After seeing the plan, the department director (with no knowledge of the effort involved) commented "But I promised the client we'd have it done by April 1 (4 weeks)." Unfortunately, it wasn't an April Fool's joke and my friend was not the least bit happy about the situation.

Another good one from the same friend was concerning a project he'd worked on for a few months. He was conducting a user training session on the new software when one of the trainees raised her hand and pointed out a fatal flaw in the software design that rendered the whole project worthless. He just stood there stunned and trying to come to grips with what he'd just been told. Needless to say the training session ended early. Apparently, no one, including the users involved in reviewing the project's development documentation, bothered to look close enough to notice flaw during the project's development.

I can't say I miss any of that non-sense.

[Mouzafphaerre]

-

SK, the reality is that unless you work for a very disciplined leader/supervisor/manager, documentation will be the first thing sacrificed when the project inevitably falls behind schedule.

MTW text scripts anyone? Or Sea Dogs obsolete model files?

Even I had to do that about five years ago; composed and sequenced full music for a play -still- with no publishable score.

Time constraints can be very motivating but also preventive ATST.
_

[el_slapper]

Programming in a bank is rather dinosaurish, too. COBOL everywhere, programs from the 70s still running in 2004, & so on. Of course, people are used to VERY SLOW development rates. So when you have the opportunity to make a whole new program from scratch, THAT DOES NOT INTERFERE WITH THE REST, it goes really fast. They gave me 1 week to make a programm, but told me "sorry, we think it should take 3 weeks to be made properly, but you only have 1 week".

The programm was compiled & executed after 2 days of intensive work. It still had some minor flaws, but the fact that it was not dependant on any of the bloody dinosaurs made it possible.

People that make video games don't have the same job as myself. I code 10 minutes, then test 3 hours, for a total cost of 2 days(paperworks & so on).

[Togakure]

It's so sad. This approach to development is why so many systems from the 70s are still in use today (you'd be amazed at how many). Sphagetti design, lack of standards, and poor documentation make it nigh impossible to cost-effectively replace them with an efficient, modern system. Oftentimes the only way to do it would be to build a brand new system while the old system continued to run in production. The old system is useless for detailed process analysis, so the end-users must be dedicated to the project to provide the crucial process knowledge. Management is loath to dedicate operational staff at the level of commitment needed because they are needed to run the production system. Risks become too great if staff are not intimately involved in the analysis and design of the new system. So, the decision is rarely made to bite the bullet and replace the dinosaur (and if it is without the proper resources available, they fail and fail and fail, costing millions; incidentally--this is a cash cow for private consulting firms who prey on government contracts for such projects).

This sadly proves that "crap documentation is job security" is true to a degree. Look at all the COBOL programmers still being employed today by governments, and institutions like banks that developed huge, intricate, linked systems 20-30 years ago. And in the case of the government (the largest culprit by far), WE are paying for it. Gah.