Ming the Mechanic:
How to write unmaintainable code

The NewsLog of Flemming Funch
 How to write unmaintainable code2005-11-29 23:59
by Flemming Funch

This is an elaborate and funny guide to how to maintain job security as a programmer by writing code that nobody else will be able to maintain, while making it appear like you just did your job. Stuff like:
Lie in the comments
You don't have to actively lie, just fail to keep comments as up to date with the code.

Document the obvious
Pepper the code with comments like /* add 1 to i */ however, never document wooly stuff like the overall purpose of the package or method.

Document How Not Why
Document only the details of what a program does, not what it is attempting to accomplish. That way, if there is a bug, the fixer will have no clue what the code should be doing.

Avoid Documenting the "Obvious"
If, for example, you were writing an airline reservation system, make sure there are at least 25 places in the code that need to be modified if you were to add another airline. Never document where they are. People who come after you have no business modifying your code without thoroughly understanding every line of it.

I've seen lots of programs that do many of the things he's mentioning. Many programmers do these things instinctively. Maybe because they have that job-security thing built right in. Secrecy is good. For many others it would be more accidental, because they didn't think about how other might need to use their work.

Many well-known open source programs are delivered with a lot of these techniques applied. And, well, that isn't really because they want it to be unmaintainable. Just because it made sense to somebody at some point, and they forgot to mention what it all meant. Or because so many people have worked on a program that it becomes a huge pile of spaghetti. Or maybe it is because the maintainers are very smart people, so it is obvious to them how everything fits together, and they don't expect lesser mortals to have a chance.

MediaWiki is the wiki program that runs Wikipedia. The code is an outrageously complex mess, even though it seems to be made by very smart people, and they obviously are maintaining it, and it works well. But on several occasions I have needed to extract something from it, and ended up giving up and writing it from scratch, because everything depends on everything else, in ways that are very non-obvious. Maybe I'm just not smart enough to touch it.

Many open source packages make sure to sneak in a few things to humiliate you, particularly if you need to compile them. "Adjust the compiler settings to fit your local environment" - yeah, that's really helpful when I don't know what any of them mean.

Lawyers probably learn many of the same techniques. Laws seem to be written that way. The small print in user agreements and contracts are usually written that way. They make it appear that they're going to great lengths to spell things out exactly, but really they're convering up the essentials, so that they know what it means, but you don't.

I've worked for managers who did this thing masterfully. I.e. keep the real information for yourself, and share only the trivial parts, so that if anybody tries to take any initiative on their own, they'll make a fool of themselves, because there's always something essential they didn't know.

French management seems to work a whole lot like this, from all I hear. I was talking with a friend I'm probably going to do some programming for, and he provides a certain kind of analysis of strategic business numbers for companies. To his surprise he found that most top managers he presented it to and explained it to would keep the information to themselves. He helps the President have some important insights into the company's operations, and a few weeks later the CEO comes and asks him for the same thing, and he realized they didn't talk with each other at all. Each of them would merely use the data to bring out as a surprise in a meeting with big shareholders, to impress them, but otherwise it would be carefully hidden.

Information is power if it is secret. Or, really? That's not the way it should be of course. And it isn't like that across the board, of course. Really, information translates into much more power when it is clearly communicated and widely shared. But a different kind of power. The exponential synergetic power of easily building on other people's work, rather than the power of exclusion, keeping everybody else in the dark, so you yourself can look a little better.

Luckily it is changing.

[< Back] [Ming the Mechanic]



30 Nov 2005 @ 00:38 by jmarc : I worked in a window factory
years ago making picture windows. Once in a while they'd send me to a different section of the plant to help out if they needed to catch up. Whenever I went to an old timers bench to learn the way to make something new , like a trapezoid shaped window or a window with 50 lites, the old timers would always guard the formulas they used, and the secrets of how they made it all work and would just give me the simple tasks like cutting stock or something. It worked out as great job security for them because it was almost impossible to fire them and hire some guy off the street like me to do the stuff, because nobody new the exact way to do the task like they did.  

30 Nov 2005 @ 20:47 by ming : Documentation
Yeah, I know that the documentation is often the least sexy part, or, yes, there might be no budget for it. Certainly, programmers usually don't enjoy it. And it is easy to get into thinking that once things have settled down, one will document everything, but one doesn't get around to it.  

14 Jun 2006 @ 11:16 by Entegro @ : great !!!
I've met my friend and he told
free nokia 1100 ringtone  

20 Jun 2006 @ 22:02 by Bailamos @ : bailanos
I believe it'll help you to be prepared to your wedding
great! I like it!!!  

21 Apr 2016 @ 19:19 by Katherine @ : bjqvoMpXstiUHe
Holy cocnise data batman. Lol!  

Other stories in
2012-01-24 00:50: Intellectual Property
2011-11-03 16:51: Seeing the world through the Internet
2009-06-11 18:53: Blogging/Microblogging and work
2008-02-23 17:19: Web 1, 2, 3 and 4
2008-02-22 11:07: Illusion
2008-01-09 22:45: A Communication Model
2007-12-02 20:41: Give One Get One
2007-10-25 21:47: Static or dynamic web metaphors
2007-09-18 22:54: Rethinking blogs
2007-07-04 23:59: Scrutiny of Information

[< Back] [Ming the Mechanic] [PermaLink]? 

Link to this article as: http://ming.tv/flemming2.php/__show_article/_a000010-001604.htm
Main Page: ming.tv