We must choose in a hundred little ways how maintainable to make our software. I wish to give you some guidance, some signposts: when you are deep in the trenches facing these hundreds of little choices, what key questions that you should ask yourself? By answering them whenever you are at a design fork-in-the-road, you will know which path to follow.
You can certainly go overboard on the maintainability spectrum. After all you do have a product to deliver. But a fair and reasonable amount of refactoring is necessary to allow the software to retain its value. So every time you roll up your sleeves and dive into the code, ask yourself these eight questions:
1) Got whitespace?
I like to see code blocked out into sections in a manner akin to how a writer blocks off paragraphs. I don't need your otherwise obvious comment lines in front of each section, just a plain intervening blank line lets me know that you are moving on to another train of thought.
2) Do you have to scroll right to read it?
If so then you are probably combining too many conditions in a single statement. Refactor into a nested "if" or if you're already deeply nested make a new function.
3) Can it have a better name?
Variables and functions should say what they do and do what they say.
4) If you were to place a debug checkpoint, what would be good to know here?
It sure compresses the coding when you do dataset.table.rows.columns[4], but it's a royal pain for debugging. If you're going more than two dots deep set a work variable for the object partway down.
5) Is your module getting too long? I chatted about appropriate module sizes in an earlier post.
6) Are the parameters that control the whole bailiwick commented at the top of your code? Are there too many of them in different places?
If you are gathering input parms from every conceivable source, maybe it's time to consolidate. You may even need to create an intermediate feeder object that collects and denormalizes all this stuff.
7) Are the logic sections... ah.... logical?
When I see nested "if" statements inside of case statements I cringe. Testing for not A or not B makes my eyelid quiver. Clean up your logic to test for eligible conditions (as opposed to ineligible conditions) and set intermediate Boolean flags.
8) Will you be able to understand this piece of code three years from now?
Perform the mental experiment of imagining that after you compile this into production, you won't see it again for another three years. Will you be able to understand what the code does? Leave yourself enough breadcrumbs to find a safe path back to understanding.
Yeah following these guidelines is a little more work, but as the saying goes: hey you can pay me now or you can pay me later.
