It’s Murphy’s Law. If it can go wrong, it will. What’s your application’s opinion on errors? If we take a stance on errors, these principles will tell us exactly how the application will behave. Shared understanding means less miscommunication. Here are some of the things I’m talking about.

Operators have the accurate information – your data is already wrong

If you’ve ever heard the following conversation, you know data entry will always be out of sync with the real world. “I know the database is telling me that bus 7 has transmission 8 installed, but I’m looking at transmission 3. Don’t tell me I can’t uninstall transmission 3, because I just did.”

What does that mean for implementation? Favor “soft validations,” warning that errors are present, but allow overrides. If I have a misallocated part in the database, I need to uninstall it from where the database “thinks” it is and mark that uninstall as something needing follow up by people in the field.

It’s all fun and games until someone dies. – The data must have integrity

Particularly in the medical field, the configuration of a medical device should be exactly what you intend with no mistakes or corruptions. Corrupt data can kill. Also, data must meet certain validations to be used, but can fail during editing.

Never write over the data file. Always write to a shadow file, test the integrity and in one atomic action, move the new data file over the old one. If there is ANY failure of integrity, the old data file is a safe fallback position.

In addition, the internal data structures might be “persistent” allowing undoing to a known good state if any operation fails an integrity check. Some transient operations might lead to bad values, like changing a medical dosing schedule might temporarily exceed safe dosages within a time frame, but you should not exit the schedule edit until the schedule validates.

If it crashes, I can use the browser, right? – The application must stay running

This is useful for kiosk or embedded applications. However some long running applications also need to handle failure.

Use multiple executables. The less an application does, the less likely it is to crash. In addition, a supervisor application can restart parts of the application that fail. Operations with risky components like using third party drivers or that can enter bad states because of bad data can run in their own sandbox and die if they ever enter a corrupt state.

There is real money involved

Real money requires an audit log. In addition, duplicate submissions are a killer and should be identified ASAP to avoid duplicate charges.

Operations, like purchases and fulfillments, are seen and recorded as first class data. The engineering team may lean on CQRS for these operations. Operations may be given an identifier early in the process. For example your cart my always have a “next order Id” so commands may be made idempotent preventing duplicate submissions.

Take a bit and think about how your application can fail and what can go wrong. Pick your battles and identify the ones that are the most likely and the ones that cause the most havoc. How are you going to handle them?

There is no correct software architecture. But there are an unlimited number of ways to incorrectly architect your software. The best we can do is state some principles and use those to help narrow the solution space of all possible architectures. This will help us identify a more correct architecture.

Architecture – a quick definition

Building Architecture is a combination of two things, making the building suitable for purpose and making the overall structure pleasing to the eye.

Making a building suitable for purpose is mostly dividing the space in to boundaries. Like rooms are often grouped near one another. Some structural considerations may help this grouping, such as bathrooms being above the kitchen to limit the number of wet walls. Some rooms may have internal subdivisions like nooks and archways that don’t limit the flow or utility of a space but visually define these regions. This defines the utility of a building.

Aesthetic considerations help make the building feel as it belongs. This means it fits in the surrounding landscape as well as feels balanced and consistent with itself. The balance and feel contribute to the habitability of a space.

Utility and Habitability in Software

Software architecture also controls the utility and habitability of a program.

Software Architectural utility is not the UX, but the software’s ability to perform its tasks quickly enough, reliably enough, and a host of other so-called –ilities. This is done by determining if you need extra caching for speed, separation of the active data set from the reporting data set, splitting the application in to multiple programs to better handle failure, and interfacing with other systems. And that’s just a start!

Software Architectural habitability is about the ease of development. Simple changes should be simple. Changes that depend on multiple business concepts interacting should only be as complex as those interactions. This is done by being deliberate about what code interacts with other code, by drawing boundaries between software concepts that reinforce boundaries between business concepts.

These forces can be in tension. Adding robustness to an application can make changes harder. Making it more flexible can degrade performance. Focusing solely on making easily changeable software if fine for small scale software. Wringing every last ounce of throughput is perfect for less complex software. Finding the balance is the art of Software Architecture.

Principles for Improving Communication

If you need someone called “Architect” on your project, the odds are you have a team larger than the two-pizza rule. That means that several decisions a day are going to need the architect to be there, and some times she can’t be present in person. Be stating not only the design goals but what purpose they serve, the architect empowers the team to make correct choices when they find themselves on their own.

It isn’t sufficient to say the software must be robust. But if we say minimize the impact of failure on non-related operations and enable a manual retry of failed transactions we are clearly stating what we mean by robust. When dealing with a design decision I can now ask myself a few questions to guide my implementation.

1. Does failure impact other users?
2. Do I have enough information to recreate this request if it fails to complete?
3. When I fail, can I undo the partial operation?
4. Are my operations Idempotent?

By stating the outcomes desired instead of the means we use to get there, the architect prevents the same problem being addressed by nothing more than a bunch of null checks and try/catch blocks.

It’s Only Business

Theses principles should come from the business case for the software. How many users are you supporting at once? Are they _occasionally connected_ or always connected? What is the impact of failure on a sale? The impact of failure on trust in the system? How about the impact of failure in the lives of thousands of children? Will someone die if your software falls down or corrupts data?

What are the reasons for your architecture choices? Have your design choices helped or hindered those goals? Is there tension between the design impacts of your business goals? Do you have some design changes to go deal with?

Music is a highly structured art form… usually. This structure makes use of repetition and variation of form. Music can be monophonic or polyphonic, one voice or many voices interacting with each other. That’s what makes it interesting as a way of exploring code structure.

Symphonies

A Symphony is a collection of songs, called movements, connected in some manner. They share a collection of themes and other musical ideas. But each song operates in its own reality.   Each song has its own musical key, tempo, and time signature giving each movement a very different feel. Each song still serves to bolster the Symphony as a whole.

Some applications have such different responsibilities we express each responsibility as a different executable program. A time sheet software may have a time entry client, a time entry server, time code management, a reporting system, and a payroll system. The themes that string everything together are the Ubiquitous Language and shared data interfaces. Each program has a shared understanding, but can act on that understanding in the manner that best fits its unique responsibilities to the application as a whole. In addition, some programs/services may serve to alter the data from one format to another, such as waiting until generating invoices to transform from a format used by most of the application to the format needed by our third party software.

Verse-Chorus Form

Your basic pop song has an internal structure called Verse-Chorus form.  The verses have similarities to their internal structure but vary differently in the content. The variance is usually the words of the verse. The chorus is the same, used to break up the verses.

We can see Verse-Chorus form in an app with several data screens, like the time entry client.  Each screen is a Verse stitched together with both a data layer and navigation framework, the Chorus.

On occasion, a song has a radical change called the Bridge. This can alter the musical key as well as rhythmic underpinnings and has little similarity to the rest of the Verse-Chorus form but serves to add interest before returning to the original structure. As our time client grows, we find reports and off-line syncing that are important to our application, but are structurally very different from itself.

Canon

A Canon is a way of manipulating a melody. The simplest example would be Row Row Row Your Boat, where the melody is time shifted by one third. When this happens twice, for a total of three instances, we get a special class of canon called a Round and can repeat the layered melody Ad infinitum.

In our time application, we can think of the canon as the series of transformations we need to apply to our employees’ time data this billing period.  We collect, group, transform, and collect again.  In C# this can be a rather long list of Linq operations.  In SQL, a very complex query.  But a lot of the data accumulation and transformation can be carefully done in parallel.  Much like a canon.

Why Care?

This is an incomplete metaphor. I wouldn’t use it as a means of laying out your code base. Instead, I can see it used to seed discussion about similarities and structure. By understanding that parts of your application have similarities and differences, the hope is we can group our code in a way that helps separate responsibilities, give clarity, and let developers quickly find the code they need.

We like to use a metaphor comparing software design to building architecture. Some people accept that this is flawed. Others cling to this metaphor too tightly, seeing developers as little more than tradesmen installing carpet in a new skyscraper.

A Building Architecture project includes a Structural Engineer. Her job is to ensure the building stands up. Her job is to determine what materials are used in the wall interiors. Her job is to make sure the windows will withstand the forces of straight line prairie winds against the 30th floor.

She is active in the design. The architect defines taste, purpose, form, function, and values. The Architect’s role is to define the spaces where she works. This, in my mind, is a very different role in software. I posit that most conflict between Architects and development teams stem from misunderstanding the role of the Structural Engineer.

Lets look at a large system. I have a web application that is used to track employee time spent on projects and turn that in to purchase orders. We have concerns about using this tool on client computers exposing sensitive data. We need to manage project membership. We would also like to use that to build employee and company “résumés” used in explaining our expertise to our clients. I’m not picking this real example because I think our current incarnation of this tool is wrong, but because this tool is an example of a large system that has many responsibilities.

What should I as the Architect spend my time doing? Should I start mandating the use of certain threading patterns? Building the ERD for the highly normalized database? Or start determining the bounded contexts, core contexts, use cases, external constraints, target response times, and security requirements?

I would get my Tech Leads in to a room and discuss how each context needs to talk with the other contexts. I would focus on how the contexts are realized and coordinate with each other. I would let my Tech Leads figure out the internals.

How do I make sure I understand the design tensions between the contexts? I would need to work on several teams, pairing with developers who work deep in the code to find where our abstractions are breaking down. An building architect spends time on site during construction for just this reason.

But I would make sure the teams are still talking, and still hitting those request times. They are my system engineers. While I may or may not know better than them as a developer, my job is to teach them to make the right choices, not make decisions for them.

This week’s blog battle has begun!

We, those of us who fancy ourselves serious developers, like to disparage the enterprise developer who specializes in a class of application called Forms Over Data. The Business needs to save some data, so they have the DBA lay out a table. The developer then points their IDE at the table and drags input element on to the form and bind columns to text boxes and BAM!, they are done. System.DraggyDroppy. It doesn’t scale to Real Development. Not when I have a rich set of domain objects.

When I started full-on professional development, the summer before my senior year, I wrote web pages. Each page was a thin veneer over the database. Until I had to add more logic and added a bunch of ifs and elses in to the page. The fact remains, the data I was manipulating was pretty anemic. I’ll call this Pages Over Data. The difference is I have an implicit Fat Controller in my CGI script that the forms over data didn’t.

As I’ve done more desktop and mobile development, I’m starting to see that I’ve just done the same damn thing. Over and Over. It’s how I’ve always done it.

Recently, I have heard several people talk about software architecture. James Coplein has been promoting DCI. At work a few of us have been thinking about rereading Eric Evan’s Domain Driven Design. Despite none of these texts exploring a new idea, despite none of these ideas being things I heartily agree with, despite having evangelized and touted these ideas; I’m not very good at it. I keep finding myself doing pages over data.

What am I seeing? In one case, we had to stand up a bunch of screens for a user study so we’ve stuck a bunch of logic in Android Activity classes. While we’ve been refactoring this out, the odds are good we will always have some of that sticking around. In another case, we had a “business layer” that another team managed and UI designed a screen at a time. Our ViewModels had a lot of logic that we decided didn’t belong in the BL as that was a representation of only the data to be saved in the file and enough logic to ensure consistency and validity and undoing edits.

I can’t put my finger on WHY I don’t like these things, but I don’t. I’m on a quest to overcome the architectural momentum I’ve developed. Here’s what I’m going to do about it. I’m reading a bunch of architecture stuff. Reading along is only so good, so I’m writing a pet project a few times to explore each architectural style I’m working with. Hopefully, this will give me a better understanding of what I’m feeling and how well these styles work for me. So the next time I’m done with a project I don’t look back and say, “it’s just Pages over Data.”