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.
