mpeever: improving the clarity and brevity of code will result in much more maintainability than attempting to make it maintainable.

kyle: Sometimes "maintainability" is about "editability" rather than "readability".

By far the worst PITA for any code maintainer (whether working on one's own code or someone else's) is finding that a particular bug fix or enhancement entails making a particular change multiple times in multiple places. Resisting the false economy of copy/paste programming is a discipline that is forsaken all too often by coders in all languages.

When you take the time to actually analyze the task at hand (many of us hold the "official" job title of "programmer/analyst, and there's a reason for that), there is virtually no need for more than one instance of a given literal string, "if" condition or computation/assignment statement. People who repeatedly copy a sequence of lines and make minor changes in each copy -- instead of creating a subroutine with parameters to handle the variations -- should be employed as "data-entry technicians" rather than programmers.

As for the proper role of comments, I agree with this point completely:

Of course comments are good for some things: as a maintainer I find it's easy to figure out what code does, and hard to figure out what it's supposed to do.

My personal mantra is: no source code file that will require maintenance should ever be written before a spec is written to explain its purpose. My personal habit for obeying this law is to start each perl file with a standard POD template (NAME, SYNOPSIS, DESCRIPTION), and this gets fleshed out with a good-enough (clear and reasonably detailed) explanation of what it's for and how it's used, before writing any code beyond "use strict;" (which happens to be part of the template). In some cases, I end up with more lines of POD (and take more time to write that) than lines of code.

This is usually so that I'll understand the file six months later, but it also helps whenever someone else asks something like "what was the spec for that procedure we did six months ago?" The POD is the spec.