Wednesday, December 10, 2014

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.


Tuesday, November 4, 2014

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.


Tuesday, October 7, 2014

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.

Saturday, September 20, 2014

Artistic Documentation


If programming is the meat of software development, then surely documentation must be the potatoes. Somewhat bland by itself, it still makes the main course more palatable and easier to digest. Generally all development projects have documents that describe its objectives. Depending on the size and complexity of your project, you may also have documents related to its deployment, operations, maintenance, and technical details.

Unless you are your own boss development starts by holding meetings with your sponsors to ferret out their requirements. A couple days after the meeting concludes, put together a formal document for the project sponsor to sign (sometimes called a Statement of Work) that explicitly demarcates the minimal need that the participants all agreed to. The purpose of this Statement should be to facilitate communication rather than to confine and restrain. Requirements change over time, so this initial spec should be "alive" and flexible.

On a large project you will next want to create design specifications for the programming staff. There is a balance along the path of a large project in cresting enough documentation to "float" the design without asking for so much that you sink creativity or subvert the sense of ownership. The purpose of a design specification should be to give the programmers enough guidance to plan their processing strategy and to alert them to what business rules might change or end up expanding.

Inside the actual programs we also find documentation. This is more or less hidden from everyone except the developers; its purpose is to serve as a memory aid and location tool when a developer goes back to revisit his code. You should compel the programming staff to write a reasonable amount of documentation: generally, a couple of lines of in-line comments for every ten to twenty lines of programming.

In addition, on a project that you expect to be mission-critical you should have the team develop standalone technical documentation that describes how all the pieces implement the business rules, paying attention to dependencies, configurable parameters, and reuse. The technical documentation should be clear, thorough, and detailed enough to allow a new member of the team to at least get his bearings in developing new code enhancements.

Although sometimes it does just seem like a chore or a side dish, documentation can make a big difference in the long term cost of maintaining a software system. And hey, some people like potatoes. (Some people really, really like potatoes... these are the folks who become Technical Writers.)



Sunday, August 17, 2014

Artistic Intent


Are you curious about what all these "ethos" posts are about, and what they have to do with designing a software system? Well like most of life's endeavors, the world is interrelated: how you comport your personal life greatly influences the results you may achieve professionally. Since people "see through" the fascia you construct, they are more concerned with the actual results of your efforts.

Work is the movement of stuff with intent and purpose; the more you ground yourself in higher principles, the better your guiderails constrain your movement. Resolving the ethos of software design usually distills to this: who do you ultimately answer to? Your supervisors may impose deadlines, restrictions, or duties that compromise your prime directives or disturb the balance between businesses interest groups. Do you follow their guidance or instead march to your own drummer?

Viewed from this level the project you are working on becomes an artifact of how you manage the relationships between all of the interested business parties. You don't constrain these relations by confining them to little boxes that you drive around the tabletop. Rather you retain these concepts in your head in the midst of your meetings and decisions: the impact of your ethos is more effective if you allow the parties to divine your intent, rather than explaining it directly.

Isn't there a lot more to analysis, like gathering and negotiating requirements, maybe a bit of competitive analysis, wireframe prototypes, and perhaps some development platform and tool reviews? Yeah sure you get to do that too, but those tasks happen within the mundane auspices of your day to day work. They occur more on the "material" plane and less on the "mental" plane. Managing your ethos however is the full metal jacket.


Saturday, July 12, 2014

Artistic Bonsai


A software developer faces dozens of constraints, from tools he may use, languages his employer supports, hardware and network availability, et cetera. But the largest constraint of software design is what lies between everybody's two ears: the capacity of their brains.

When you are initially designing a system and have finished your requirements solicitations and focus sessions, the first challenge that pops up is how to structure the functionality of the system into something that overlaps adequately to the mental capacities of those who will use it. They possess a certain capability to remember paths of navigation and where to set various field values to achieve specific business objectives.

Brain capacity also tends to limit the creative canvas of developers: you need to know enough of a subset of current technologies to be useful, yet you have to leave adequate "internal storage" to accommodate the intricacies of the domain knowledge for your employer and their industry.

Hence brain capacity planning is similar to bonsai gardening: the constraints force you to be artistic within the limits of your containers.



Wednesday, June 25, 2014

Artistic Simplicity


In an earlier post I pointed to some general principles you should abide by when developing software. Two of these, parsimony and perspicuity, could use a bit of further elaboration. Together they delineate the promotion of a simpler approach to design. Why is simpler better?

As the saying goes, "there's more than one way to skin a cat." Relax it's just a saying, I have nothing against cats. The point however is that given any coding challenge there's usually an algorithmic technical nifty way to get it done, and a more lengthy but more easily understood mechanical way around the problem. The technically elegant way will execute faster and may allow for some future bells and whistles that can be accomplished with just a couple of extensions. The more transparent, simpler to understand, lengthy code will take longer to execute and will require more lines of code when it eventually becomes time for a new feature.

But frankly the longer code is easier for a novice to understand. And in the modern corporate world of high employee turnover, constant technological change, and shifting management fads, the longer code -- because it can be maintained by newcomers -- realistically has a greater probability of staying in use.

Simplicity begets Longevity.


Monday, April 7, 2014

The Art in Beauty


Whether we are consciously aware of it or not, in the midst of development we make hundreds of tiny decisions that reflect a choice in "beauty". Mostly these boil down to a decision for what level of elegance we will apply to a design approach: whether to hack away at something until it works or whether to design the code with an eye toward easing future maintainability.

In the old days we used the shortcut terminology of "table-driven-design" to signify the latter case, but nowadays designing for maintainability is much more than this (see for example these earlier posts).

For now though consider this interesting metaphor to beauty: just as a person can suffer equally from both too much beauty or too little beauty, the same can be said for the elegance and maintainability of a software system. If something is hacked together in an ugly and hasty fashion then not only will you have to support it forever, but you will grow gray or lose all your hair in the process. Conversely if you design something that can be maintained and extended simply by adding rules to a SQL table then your employer doesn't really require your continued ongoing services.

You must therefore choose an appropriate level of elegance in the same way that people choose their level of beauty. This has all sorts of philosophical and aesthetic consequences that I examine in a different category.


Friday, March 7, 2014

Artistic Arranging


In the windows-form world menu layouts are pretty settled, but no standard has emerged yet in the web-form world.

In a windows form try to keep your menus parallel to how Microsoft has theirs laid out: always a File menu at the farthest left, and a Help menu farthest right.

Use horizontal separator lines to partition out items of similar function, and be sure to enable hot-key shortcuts to the commonly used items. You should avoid a single item alone between separators. Menus shouldn't exceed eight or so items in any dimension (per pulldown or across) and shouldn't pop-out more than two deep, although I usually require a fairly serious reason for any pop-out after the first one.

Interfaces on web forms are tending toward an artificial "tabbed" approach. This works reasonably well provided you stay consistent with fonts, vertical spacing and presentation layout. More than three levels deep of tabs looks ridiculous; at that point its better to partition master pages into separate functional groupings. Avoid mixing horizontal and vertical menus on the same page and use a consistent menuing approach throughout your application.

Laying out menus is an art all its own. It's rather like playing rhythm guitar -- take the time to do it right and your menus should look good, be clean and intuitve, and stay in the background.


Monday, February 10, 2014

The Art in Ownership


Every analyst who has been called in to a consulting gig recognizes that money, the capital behind the business, carries a fair amount of power. He who has the gold makes the rules, and all that. The actual relationship between a company's owners and its employees is however substantially more sublime. The primary power at owners' disposal is hiring, firing, and purchasing, but they may only exercise these within the constraints of their detailed knowledge of the actual day-to-day operations that their employees support. This is where your role as an analyst faces its greatest challenge: in effect you are pinching the constriction of knowledge as it straddles across the employees and the management.

I have only found two ways to respectably play my cards as an agent of knowledge restructuring between these two parties. The first option is to nominally side with management, the second option is to firmly stand by the employees. In the first case you become an extension to the desires of hatchet men, using their power indirectly while pressuring the employees to reveal their knowledge. This method is best executed from the role of an outside consultant.

The second alternative, siding firmly with employees, requires that you nonetheless "package" your presentations to appeal to the baser, monetarist side of management. In either case you need to remain a bit guarded and two faced, hence in the end falling a bit short of the unrealistic expectations of both parties.

Society imposes its wishes on business owners with a large and diffuse glove, that can occasionally sprout spikes of glistening razor-sharp titanium. Enforcement can sprout as tax compliance, licensing issues, fair trade rulings, patent law, or numerous other sundry regulatory appendages. Occasionally you may find yourself defining a system with some sideways legal considerations. The safe way to approach this is to make sure that /some/ sort of audit trail exists, should management decide that at some point in the future they need to more tightly, retroactively, comply.

The symmetry between a businesses' owners and its customers is perhaps one of the most deeply studied aspects of capitalism. When all is said and done however it really boils down simply to two managed aspects of a buyer-seller relationship. The owner/seller is trying to optimize the services and products they will provide, and the buyers are choosing the best "value" given their variable and shifting tastes. As an analyst you are therefore trying primarily to implement a system that provides both immediate and ongoing value-added efficiencies. Customers can sense however when they are being manipulated; be wary therefore if your system is going to provide further margin to your employer without a concordant benefit that gets passed along to the customer.


Monday, January 6, 2014

Artful Traceability


When you are in the actual throes of day to day production… after the development is done and you work out most of the bugs… it certainly is convenient to have some sort of end-to-end Traceability. The general concept is that every change in state or activity that has a material financial impact to the company (or its customers) should be traceable back to underlying actions.

The idea is somewhat similar to how an airline keeps track of its design and maintenance records. When a portion of the avionics fails during a landing it sure is nice to look back through the records to see what parts get linked where, and what has changed.

For example, at the end of the month you send an invoice to your customers. Where do the line items on this invoice come from: what atoms of work and activity (from a systems viewpoint) do they represent? Can you trace back from an invoice number back through shipping, fulfillment, ordering, and customer options?

Many time validation is just viewed as comparing the results of production back to the functional specs to make sure all of the business rules got implemented correctly. But validation should also be enabled for ongoing activity in a dynamically changing system, and this requires designing for traceability, from the very start.