How To Write Unmaintainable Code

/ writes "Roedy Green of Canadian Mind Products has written an essay entitled "How To Write Unmaintainable Code". Following his 54 tips, you too can guarantee job-security by becoming irreplaceable. If that weren't good enough, it's even available in Spanish. "

Maybe you shouldn't be working for the place.

Writing unmaintainable code for job security is a Bad Idea (TM). Cuz guess what? You might end up the victim of your own practices -- and who's going to get fired when they've failed to figure out code they wrote a year ago? You. Don't do it. Maye you should work somewhere else where they know how much you're important and valuable to them, so you don't have to take such measures as to write bad code. And if you're going to get replaced so easily then maybe you were not worth your salt in the first place.
------------------------------------------ -----

Re:the secret to my success

Huh, that brings up an interesting point. What is better, to write crappy code or to take the time to make it nice and neat? From the programmer's perspective, it makes sense to write crappy code: bosses are demanding you finish projects before you even begin them, and good takes time to write; also, like you mentioned, job security is nice indeed.

However, don't we, as programmers, have some sort of obligation to try our best to create nice, maintainable code? I may be getting a little too philosophical here, but we expect artists to paint to their best abilities, poets to write to their best ability. It seems like if someone in one of these professions purposefully wrote sloppy poetry, or half-assed a painting, that we would look down on them. Perhaps it is a pride thing, but you think you'd intrinsically want to write good code.

I am not trying to sound preachy, CFN, for I don't know if you wrote sloppy code because you wanted to, or, more likely, because you were rushed and your superiors favored quantity of quality.

For folks who complain about VB ....

I Quote from the essay .... Maintenance programmers, if somebody ever consulted them, would demand ways to hide the housekeeping details so they could see the forest for the trees. They would demand all sorts of shortcuts so they would not have to type so much and so they could see more of the program at once on the screen. They would complain loudly about the myriad petty time-wasting tasks the compilers demand of them.

This is precisely the reason VB is so popular for business apps. You have to really work hard to confuse matters sufficiently in a VB program so that a decent maintenance programmer can't figure it out.... although I could write my own list applicicable to Vb for my current project... My favorite: Make sure you have the same variable name to reference a database in several different classes in several different programs, but have it point to three different databases depending on which variable is in scope currently :)

Maintainable Code

To write unmaintainable code is a very unworthwhile thing to do, because you will be essentially married to the code until you find somebody to which you can explain it.

Personally once I write some code I want it to be maintainable enough so other people can contibute for I can move on with other things. I do not feel that my life consists of solely maintaining code, why not do something challenging? Rather then babysitting one of my past accomplishments. Why not take over the world?

Fit all code on *one* page.

Back in the good old days of DOS (and thus, 80x25 page size), I had a programmer in my team who followed the "all functions must fit on one page" rule...

Man, the number of times I wanted to kill that guy. We called him Anti-Whitespace.

Scarey though, how that page gave guidelines that I myself have been guilty of following too many times in the past. Is there a counter-page to that one, that gives guidelines (general purpose) that make it easier to work with other programmers?

As an architect

I hate it when members of my team write unmaintainable code. Frequently, when time's short or when people need help, I have to dive in, and I've found it difficult to get my bearings in code that I did the initial design for - difficult to see the forest for the trees, even when I planned out the forest.

Good practises in programming isn't just for academics; it's the epitome of professional code writing. A manager once tried to draw the definition of a hack and a real programmer by the completeness and bug-free state of their code. I think he's wrong. I think that a real hack writes code that no one can pick up. A real programmer writes code that anyone can pick up and fix or expand - whether it's complete at any one point or not.

--

Removing toungue from cheek...

The first n years of my career were spent maintaining old code. Assembler. I vowed "I will write maintainable code".

Now I write good code. Maintainable. Well commented. Meaningful variable names. Nothing fancy. I know what it's like to revisit my code ten years later.

There is a problem, though.

Nobody else seems able to maintain my code. They just can't understand it.

Despite high-level pseudo-code algorithm descriptions, threaded comments, good up to date written documentation, they just can't wrap their tiny little heads around how I do things.

I can go back to something I wrote 15 years ago and fix problems without generating new ones. My code is robust enought that I can shovel out a few thousand lines and jam in another 10,000 lines, test it for a day or two and release it... and get no bug reports for another 5 years. I consider this to be maintainable code!

Go ahead... break all the rules suggested in the article. You may still produce code that other, lesser programmers simply can't cope with. The code is an expression from the mind of the person who wrote it... and sometimes writing to the lowest common denominator simply isn't possible.

And then they blame you for writing unmaintainable code.

The REASON we want good code...

It's not a philosohpical issue, it's one of practicality:

When (not if) you end up maintaining someone else's code, if the code has been written in a clean way, it can be a sure joy to work with. If not, you'll be cursing that programmer for eons.
(Lets keep Microsoft's API out of this ok ;-)


The REASON we want good clean code is so that _we CAN_ maintain it.


I have been in the position of looking at my own code 6 months, later, and gone "WTF?", and wasted lots of time trying to figure out just what the heck I did.

If I had just spent the extra time to begin with, later on I could of been more productive instead of wasting time re-engineering the damn thing.

Pay the piper up front and save time later, or be a "saving time" grinch, and find an expensive time bill later. Seems pretty obvious what "The Right Thing" to do is ;-)

Work smarter, not harder =P

Cheers


BTW, Steve McConnel has a great book: Code Complete.

War story

We had a system with about 750,000 lines of assembler, doing some heavy-duty, real-time math modeling of oceans. The hardware was old. The contractor said they'd deliver a modern system with the code in C.

They wrote a converter that digested the assembler and produced C code... about 4 lines of C for each line of assembler code.

So a math calculation that could easily be written in 1 line of C took 30 or 40 lines of assembler which converted into 120+ lines of C. (Stop screaming!)

Their converter did not put the original source line as a comment in the new source. (Now you may scream!)

Now I gotta maintain this pile of compost. I'm looking for another job.

Thingy!

In naming functions, make heavy use of abstract words like it, everything, data, handle, stuff, do, routine, perform and the digits e.g. routineX48, PerformDataFunction, DoIt, HandleStuff and do_args_method.

He forgot "Thingy"! How can you forget "Thingy"? As in "Take the thingy passed in by the user, send it through the thingy, and return the thingy to the user" and "Merge the two thingies, extract the resultant thingy, discard the other thingy, you don't need it here, and then pass the thingy on to the next thingy."

Don't normally defend sun but..

Ignore the conventions in Java for where to use upper case in variable and class names i.e. Classes start with upper case, variables with lower case, constants are all upper case, with internal words capitalised. After all, Sun does (e.g. instanceof vs isInstanceOf, Hashtable). Not to worry, the compiler won't even issue a warning to give you away. If your boss forces you to use the conventions, when there is any doubt about whether an internal word should be capitalised, avoid capitalising or make a random choice, e.g. use both inputFileName and outputfilename. You can of course drive your team members insane by inventing your own insanely complex naming conventions then berate others for not following them. The ultimate technique is to create as many variable names as possible that differ subtlely from each other only in case.



(e.g. instanceof vs isInstanceOf, Hashtable)

they are all valid w.r.t the conventions.

instanceof is an operator and a keyword hence should be all lowercase, isInstanceOf is a method name, hence should start with a lower case character and the rest of the words should be capatilized, and Hashtable is a class name hence every word should start with a capital. Hashtable is the only one you could argue, but I'd say that sun just think Hashtable is one compounded word in itself not two words that describe a class's function.

Some more rules

WARNING: 20 years of looking at, fixing and replacing bad code about to be vented...

• Put all your code into a single function. (I've seen functions over 2000 lines in length.) After all, those nasty functions generate overhead on each call, and you want your code to be efficient right?

• Use hungarian notation for variables. Then instead of the overly verbose

  int numLinePayments; char *maxTypeCode;

  you have the nice and compact

  int iNmPt; char *szTyC;

  BONUS: With compact hungarian notation, you can become even more descriptive! So really the above becomes:

  int iLnNmMtCsByPt; char *szMxQtBlTyAcC;

  So much more descriptive information, all in the same amount of space. I've been on projects using this, and the sheer of joy of it cannot be accurately described in words.

• Don't indent your code uniformly. (This is a variation on #11 from the article.) Use Windoze or vi editors, with non-standard tab widths, for tabbing and indenting, which means that no one can see your code indented properly unless they use the same tools you use, with your same editing configuration.

  BONUS: Write extremely long lines of code, well over 80 characters per line.

• If using C or C++, don't use memory analysis tools like Purify [rational.com], or its open source equivalents. After all, if you find your bugs too quickly, you might lose your job.

• On large projects with several programmers, make sure you change global header files that cause everybody else's code to break but yours. Do this late in the afternoon, so all hell breaks loose breaks right before people are going home, or late at night, so that everybody comes in fresh the next morning and wonders what the hell happened to the code that compiled perfectly when they left the day before. Either way, make sure you are not around when they find out! Otherwise you spare them the joy of figuring out what you changed, and why.

  BONUS: Do this right before a major deadline.

• Do really stupid stuff that you were taught from day 1 not to do, but everyone seems to do anyway: don't check for NULL, fix array sizes where you hardcode the max size everywhere, don't check for invalid or oversized input, etc.

• Use preprocessor macros. Lots of them. (I was actually on a project where someone suggested using cpp to define macros. For Java. Absolutely brilliant!) The key is to use a single macro for multiple statements, in effect using macros as function calls. Example:

  #define DO_STUFF(x,y,z) if (x else more_stuff(z); \
  mystery(a*2, z-1); \
  for (int n = x; x != foo; x--) \
  more_stuff(n - x);

  Notice the "hidden" use of external variables and functions. Remember, you want to avoid those expensive subroutine calls! And think of the joys of setting breakpoints and stepping through a debugger on that code!

  BONUS: Don't use the all uppercase convention in macro names; use the same naming convention as function calls. It's even more fun to debug when you have to spend time actually figuring out do_stuff() isn't even a function call!

  MORE BONUS: Nest macro calls. Use the naming convention above.

  EVEN MORE BONUS: Use macro calls as variables. Make sure the expanded macro makes function calls. Or uses other macros.

• Don't use source code control. Or, use it, but never unlock or checkin your files. Feel free to steal locks on others, though.

And finally, one of my favorites, for all the young and aspiring hacker types out there:

• Write code only for yourself. Assume no one will ever need to figure out how to use your code without poring through it in painstaking detail. Do not make it easy to use, interface with other code, or even compile. Include 30 caveats that would take you only a few minutes to fix, but you're just too lazy to. In other words, write as if no one will every look at or use your code, yet release it to everyone to look at and use. Defend your laziness, which is causing thousands of lost hours of work to others, by uttering useless and stupid "cool hacker" mantras like "Real Programmers don't write documentation" and "If it was hard to write, it should be hard to understand."

Phew. That little tirade made me feel good. :)
----------

Mirrored here - really :)

Mirrored here [adboink.com]

Enjoy

Re:Removing toungue from cheek...

Oh dear, oh dear ...

My company (owned by me) started a small contract last month at "a small financial services company" (let's not be too specific). About two years ago, they started to migrate off of DOS, a small 3090, and some netware boxes to Solaris. In the meantime, their workload has been growing. The old mainframers decided that they didn't like UNIX and waged a two year war to get rid of UNIX. All the UNIX guys left. Then they bought out two larger (but apparently worse-run) companies that were run completely on, you guessed it, UNIX. The mainframers announced that they were old and tired and perhaps they should bring the UNIX guys back (they were apparently told that they didn't have a choice). But they wouldn't come back (lots of work in Dallas for good UNIX guys, without rabid mainframers in the next cube). For the last nine months or so, they have had one group of "Unix" "consultants" from most of the majors over there "trying to fix the code" that they inherited. The code? perl. Just perl. A little ksh junk, some C, mostly perl.

I (and two other people) are now 10% done (we estimate, and we are usually right on estimates). None of us can figure out what was so hard about the code. Really. Some of these "consultants" had teams of 20+ people here. I think that they must never have seen UNIX before in a production environment.

This industry is very, very full of the clueless, and not all of them are running NT (most, yes, but not all). When people keep talking about the coming IT salary shakeout, I think of situations like this, and lots of others, just from the last few years. Good people will always be in demand. The lusers will rapidly find it hard to pay their bills. And this is not new -- it is just filtering from the most structured areas (that would have been MVS/COBOL shops) to the least structured (just wait, web-designer weenies -- your time will come), and it is hitting UNIX now. I think that the excuse of "this is just wild and crazy code and I no mortal man could wade through this spagetti" will soon hold as much water as "it's the compiler -- it hates me!" Heh. With this company, they were not clueless -- they kept the 3090 and never ever seriously considered NT. But UNIX was still believed to be bad juju and scary, so they accepted the explanations. I suspect that they won't in the future, as we are not missing chance to point out how clear things really are.

And, as an aside, not a single one of the COBOL guys that I knew (actually, a lot of them were and are women) were never out of work more than a few weeks, and some of them have been keying for dollars since before I was born (1970, folks). Their only recent job changes have been to jobs paying $200+ an hour.

Personally, I cannot fscking wait until some of these Thai-stick Bogarting full-of-BS tool-dependant Shockwave-inflicting pretentious "artist" wannabes that make web front ends to business site such a holy terror to implement for those of us with actual skills (like perl and DB2) start being forced on pain of no work and subsequent drug withdrawl to fscking write fscking proper fscking HT-fscking-ML to the fscking spec the client fscking asked for. Without the little moving GIFs. Grrrrrr ...

Re:Maybe you shouldn't be working for the place.

Rule of thumb here.. Write two sets of code, one with utter drivel, the other well maintained.
One you don't shoot yourself in the foot..
Two you have job security...

Spirit Breaking 101 for Junior Porgrammers.

as a cs student, nothing inspires me more! job security rules!

Good evening class. I'll be your exorcizer of idealistic nonsense for the evening. Just call me Bruce.

Now... preach all you like about how hard it'll be for the next guy, but like customizing my car or my house... I don't worry about what the next guy will think about my code. Do you care if the next owner of your car might not like it if you paint it red? Do you care if the next owner of your house disapproves of you converting the garage into a pool room? Heck no. Well, it's the same with me. I work for my own benefit, pleasure, and satisfaction. And to do that I've gotta do the best damn job I can at work. Otherwise; no money; no fun. This philosophy is reflected in my code as well. I've cranked out some godawful nasty kluges that confuse even me when I look at them a year later... but I got the job done, by the deadline, while some of the junior programmers seem to wanna rewrite everything to make it clean rather than break the nice design of the code. Feh. That's why they're junior programmers. They Just Don't Get It (tm). Their plan would send the company under. Stuff's gotta be done now and ship next week or there's no profit for the company and no salary for the programmers. Junior programmers always seem to be self-delusional with grand plans of redesigning everything. It never happens. Requirements change *ALL* *THE* *TIME*. Any static plan is doomed to fail. Once they realize this they make the transition from dreaming programmer to master hacker... or they can't keep up with the pace of real world business and disappear. You've got to be able to deal with old crusty projects written by long gone staff with more bags and bells and whistles and ornaments hanging off the side and kluged into it, written by more people you've never met, and you've got to be able to quickly and successfully hack more stuff into it and hack it and rehack it and change old stuff and keep it all running. Successful, on the fly, under the gun kluging is what distunguishes the Senior Programmers driving the big smog polluting, shitty mileage, comfy luxury cars into the front, covered parking space and getting the stock options and profit sharing and 401Ks from the idealist larval dreamers driving their small car becuase "it's good for the environment". Self-spirit-lifting-and-self justification-bull. Given the Big Bucks, you'd ditch that Civic for a gas guzzling SUV or Corvette too. So forget the dream. Getting a clean slate to build on is a rare event. 99% of all programming jobs you'll ever be hired for will be holding together someone else's code. Insane deadlines, getting the jump on the competition mid project, reamping of requirements (many times over), decision reversals by management, your latest self-gratifying achievement being abandoned and dumped because it's not needed anymore. These will all eventually break your spirits. On the plus side, once you realize this, you will be able to succeed and advance within your company or find it easy to get hired at the next comapny. because quick thinking master hackers who can do the magic again and again despite laying waste to the original vision and still keep on kluging and have it keep on working are what companies want. If you can do this, you will succeed. Getting back to the original question... do I obfuscate my code? It may certainly look that way to the idealist, but not so. True brilliance is messy. Remember the famous comment preceeding the task switching code in Unix... /* You are not expected to understand this */ But if you can, you'll be a god... or root... what's the difference again? Anyway, class dismissed.

Job security

Remember the old motto...

If you can't be replaced, you can't be promoted.

if else if else if else if else if else if ...

Some of my favorites, all of them true stories about code I had to maintain:

• If your program executes one of many different unrelated functions on each run, don't use any of them steenkin' Commie pinko data structures like a dispatcher table, and for Pete's sake don't split the various functions into different source files. Put it all into one enormous if ... else if ... else if ... statement that extends across 10,000 lines. Hey, if they want to change a line of your code, they better be sure that the whole thing still compiles.
  
• If you must break up functionality into subroutines, use global variables with reckless abandon!
  
• Whitespace slows down your compiler or your interpreter! So cram that code into as few characters as possible! (I had a colleague who really believed this.)
  
• Are you worried that upgrades to system libraries will break existing programs? No problem, just install them on some non-standard path, like in your home directory, and link them in from there. You don't need to tell your colleagues where to find them, because surely you'll get around to re-installing them in the right place Real Soon Now.
  Say you're programming CGIs in Perl using modules. Whatever you do, don't install new modules in the system-wide site library, because that could cause all kinds of trouble! Better to put them all in /cgi-bin/lib/ and use use lib '../lib'; to bind them in. But what if you have test scripts in /cgi-bin/test/? No problem, just install the same modules all over again into /cgi-bin/test/lib/ (don't be too picky about whether you're using the same module versions). And if you have mod_perl registry scripts under /perl/, then install all those suckers under /perl/lib/ and under /perl/lib/test/ all over again! So what if you end up with four different versions of the same modules, at least you didn't take any chances the system-wide installation.
  

The problem with becoming invaluable...

Is that you get chained to your code. The volume of documentation on my code is bigger than my code, because I can hand it to someone, say "this is all you need to know", and leave that code behind. Forever. On to bigger and better projects.