Code For The Maintainer

It's always a good idea to CodeForTheMaintainer.

(Though it is an even better idea to be the maintainer. I have made my best programming discoveries while wallowing in the complexity of maintenance situations. This can be quite rewarding unless the code base has already been made too brittle to do the work properly. -- WardCunningham)

The reason being that maintenance is by far the most expensive phase of any project. cf. CodeComplete by SteveMcConnell for some statistics on this.

Thus, it is best to help reduce costs for the maintenance phase.

SelfDocumentingCode, etc. are good techniques.

In general, if you keep in mind someone with little knowledge of the system will come after you to change the code (FractalComprehension), not only will you write clearer code, but you'll tend to limit the amount of damage that people will make through mistakes.

In other words, make it easy to change the system with limited impact.

Always code as if the person who ends up maintaining your code is a violent psychopath who knows where you live.

I usually maintain my own code, so the as-if is true.

Alternatively, always code and comment in such a way that if someone a few notches junior picks up the code, they will take pleasure in reading and learning from it.

The mention of magic word HungarianNotation brought on the usual grumbles

[EditHint: Probably the below should get moved into one of the Hungarian notation pages. I don't know if we should put a disclaimer on the original statement; I've come to assume any statement on Wiki, especially if it contains a link, is going to have a pro and con discussion. I'd do it myself, but vacation is coming up in 4 or so hours, suckers. -- JoeWeaver]

I am shocked to hear HungarianNotation described as a good technique for writing maintainable code. It is a direct violation of OnceAndOnlyOnce, as it records the type of a variable both in the variable declaration and in the name. While changing the type of a variable is not all that common, it does happen, and it is not helpful to suspect that somewhere in the code lurks:

String iErrorCodeThatUsedToBeAnInt;

-- RussellGold

I agree completely. HungarianNotation is a BadThing.

Perhaps the need for HungarianNotation is only a smell of the BadThing, a cruel compromise made only because finding and fixing the root cause was out of scope for the Hungarian who invented it.

As long as you're being dogmatic (re: OnceAndOnlyOnce), changing the type of a variable and not changing the HungarianNotation decoration is not coding for the maintainer. If you want to be strict about some dogma, I would think that CodeForTheMaintainer takes higher precedence over OnceAndOnlyOnce as the latter is a technique to help accomplish the former. -- SunirShah Of course, years later, now I hate HungarianNotation. Your mileage may vary. -- ss

"HungarianNotation is a BadThing."

Conversely, a (limited) form of hungarian means that the maintainer never has to worry about where gsFoo comes from, or how much affect he'll have on the system by changing mlActiveState's value. Speaking as someone who has had to upgrade/maintain a legacy system which did not use HungarianNotation: global variables without scope information are nightmares of ever expanding refactoring waiting to happen.

If the var type changes, the var's name should change along with it. It also gives Coders who follow you a better clue as to how you intended said var to be used, and in my mind it is the very essence of CodeForTheMaintainer. You (generally) know what you're doing... it's the next guy who needs the help. -- AaronCumming?

Try using Find/Grep/Search in lieu of Hungarian. In general, never screw with a variable until you have looked at its scope and everywhere it is used. If one cannot quickly tell the difference between a local variable, a parameter, a class/module variable, and a global variable, perhaps one should rethink programming as a career.

My point exactly: a little naming convention saves your maintainer a few hundred Finds/greps/searches. I'm not advocating cowboy refactoring, or not checking the usage of variables before one makes changes to the code. Just saying that a code maintainer who doesn't have to check the use of -every- variable in a function to ensure that it's not improperly scoped (i.e., global counters, global strings used as flags in functions which are always called immediately afterwards, the global "i" var, etc.) has less finding to do, and can focus more on the task at hand.

global variables [...] are nightmares [...] waiting to happen.

On HungarianNotation - it can be a good thing, when used properly. Unfortunately 99% of the time it's the wrong sort of hungarian. See Joel Spolsky's "Making Wrong Code Look Wrong" (http://www.joelonsoftware.com/articles/Wrong.html) as an argument for correct use of hungarian. Hint: hungarian shouldn't be used to decorate primitives.

HungarianNotation helps... except when it doesn't. If you don't keep on sync the type and the name of the variable, you will have troubles.