More Artful Beauty

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.

The Art of Survivability

In the rough and tumble world of the development of corporate software most companies establish "checkpoints" to assure that their engineers don't get too far down the river before they realize that they needed a paddle (or an outboard motor). How they implement these inspections (with paperwork or process) varies greatly, but the overarching principles are standard. What a company needs from its software operationally in order to prevent a black-swan failure is:

1.       Scalability – developers need to demonstrate right from the start that each successive implementation will meet the *eventual* maximum usage envisioned (in terms of concurrent users and fully loaded database tables).

2.       Trackability – every release should document what changed or got added -- in a public location -- for everyone to see.

3.       Knowledge base – all modern software is so immensely complicated and rapidly changing that it is impossible to keep the technical documentation up-to-date.  Therefore to support maintainability at least two full-time Permanent (in-house employee) software developers need to know everything about any particular system.

4.       Operationally Repeatable – Production controls must exist to allow for the restoration and re-running of a system from any arbitrary point.

5.       Archivals and Deletions – You need utilities to remove old data to prevent the gradual quicksand degradation of performance that will  suddenly cause a cascade of timeouts.

6.       Implementation Rollback – anytime a major software change gets implemented you need a way to roll it back.

Those are the biggies in general philosophical terms. Yeah this list probably doesn’t help much down in the weeds for what documents or gateways to put in place, but it’s a good start for group discussions to get there.

The Art of Approach

The Systems Analyst comes in three distinct flavors (much like vanilla, chocolate, and strawberry). Those just starting out seem to be more document, process, and requirements-solicitation oriented. They walk into a business and hear that we need to build system ABC, and then they ask who knows the most about how ABC should work, and they go about gathering requirements. The more astute Analysts may have tools they employ to promote a cleaner solicitation, certain tricks of the creative trades. Their basic premise, the "flow" of what they manage, is from the "tribal knowledge" of Subject Matter Experts, through documents, and then passed along to Developers. Of course the Systems Analyst has a fair amount of practice in the realm of software development, so she knows how to translate departmental objectives into the procedural data flow and structured specifications required to support the creation of computer software.

Another sort of Analyst exists though, often termed a Business Systems Analyst. To start with,  a BSA has more of a business management background, and frames things more in the realm of strategic planning. To a BSA the entire corporation is a means to an end, often a complex blend of monetary and social objectives. Hence the nature of what "flow" a BSA manages is ever so slightly different. He too ends up providing direction to software Developers, but his perspective is less the straight line delivery of departmental information rules to programmers and more the slow changing of the culture of his workplace to facilitate efficiency and service. Some of this includes requirements solicitation, but much more of it encompasses providing a basis for more open channels of communication amongst the staff. He is striving for synchronicity.

Nowadays I suppose you have a third sort of Analyst, although they don't go by that title.  In an Agile environment we have the Scrummaster. He has more of an internal entrepreneurs sort of perspective, living within the constant flow of business changes and potentialities at the intersection of resources and technological possibilities. His objectives are both continuous improvement and disruption.

Due to the substrate of personalities required to pull off these three roles, these tend to be distinct people with disparate approaches.  It's not unusual however, even a medium size company, to have a Neopolitan mix of representatives from each.