Skip to main content

Hell is other people's code

Jean-Paul Sartre said: "Hell is other people".

To which I say: "Hell is other people's code".

All kidding aside, working with other software developers' code can be daunting enough, even when the code was written by diligent, conscientious engineers.

It becomes downright nasty, bordering on torture, when it was written by someone unconcerned with the need to maintain the code later. I wonder, when working with such code, what level of Hell I've landed in.

I've seen near-identical functions located adjacent to each other in the same file, each differing by only a few characters here and there, and both spanning a half-dozen display screens, making it impossible to even tell which function you are looking at. Each having conditional compilation controlled by the same manifest constant with a near-meaningless name. The second function body #undef'd the manifest constant before the first line of the function. So there was no way to know, when looking at a particular screen full of code containing conditional compiled statements, whether the code was compiled and active in this particular context.

I've battled the vile demons of magic numbers, copy-and-paste code as a means of code 're-use', low-level communication code that pops up blocking error message dialog boxes in the middle of threaded data send routines, what-should-have-been-library-code-but-was-just-another-source-file (used in a GUI application) that unceremoniously calls exit() when an error occurs in the middle of an initialization routine.

All the while, I'm repeating to myself: "I have no mouth and I must scream".

So: When you write or maintain code, please try to keep in mind that someone else may need to read, understand, and even - *gasp* - modify the stuff you are generating. It's a good way to help make the world a better place. Really.

Resist the temptation to take that shortcut. Drop a few comments describing your assumptions. Sprinkle the code with a few assertions to describe the conditions required for proper operation - but don't rely on assertions to provide runtime error checking; use exceptions or well-defined return values if you must. If you know about a precondition or gotcha, make a note of it for the benefit of others. Do something, anything, to improve the condition while you are working on the immediate need.

Take the time to think about those who follow - They'll love you for it.

... and that person may be

... and that person may be yourself in six months, or a year, or two years.

Bingo!

Damn right. Some people seem to be gluttons for punishment, though. So, if I can help convince them to do something to help others, then they may be helping themselves too.

This diatribe was intended to remind software developers of a broader responsibility, though.

A little late

I just stumbled upon this text while typing 'php how to modify other peoples code' in google. Started a new job as a PHP developer six months ago after a 15 year consultancy/system engineering career and I found myself in hell, when I heard last week that I had to become a specialist in such and so application which was bought by the company. Since I'm still a junior programmer, I became overwhelmed by this application and reading this blog entry right here, helps me understand that this is, can and shall be part of being a software developer who has to maintain other peoples code and I can stop pulling my hair out for not being sure if it's my inexperience with the job, or someone elses sloppy work.

I can relate to finding functions with almost the same name in the same file. Even to functions with the exact same name, in different include files doing the exact same thing but (in my limited understanding) , it's random which one is invoked.

And don't get me started about the cheerful combination of html, php, js and css all throughout the files which makes it extremely hard to follow even the simplest of control structures.

Anyway, I was considering looking for a new job, back to consultancy but this blog entry made me reconsider.

Thanks and sorry for ranting ;)