Information Systems Architect should write solid code, Part 2, how?

Code is the most efficient way to convey ideas to programmers. Architecture code should be embryonic, a starting point for a solution. Architecture principles help when they define some ground rules for composing solutions out of components, the boundaries and contexts of these compositions and the special conditions that should be guarded. All this can be expressed much faster in wireframe code, than in complicated text. If you can express architecture principles in diagrams and text, be sure to also express them in solid code. I call this say it in code.

In an earlier post, I stated that an Architect should write solid code. I’ve also tweeted about this, pointing out that an IT architect who doesn’t code cannot be trusted. To illustrate my point, I chose a fictitious test case organisation, Trotters, where Kermit works as an Architect. I described some of the consequences when someone like Kermit is far removed from code. If you are interested in this discussion but haven’t read my earlier post, I invite you to do so here.

In this post I will discuss some of the ways that Kermit could write code to make the architecture practice more effective in his organisation.

To begin with, here are some more (bold) statements – I could always prove the points at a later stage.

  • If you can draw diagrams, you could also provide framing code base that realise the diagram
  • If you cannot create code representative of the diagrams that you are drawing, then either:
    • you are unsure how to do this (no further comment on that), or
    • your ideas are not fully fleshed out yet (so you are not done), or
    • you are reluctant to get into the details, for some reason
    • In any case, this is a problem.

Writing wireframe code goes much faster than writing long documents, and it harmonises interpretation much more efficiently. Text and diagrams leave a lot of room for interpretation, every programmer is likely to interpret things his/her own singular way.

Code is the most efficient way to convey ideas to programmers. Architecture code should be embryonic, a starting point for a solution. Architecture principles help when they define some ground rules for composing solutions out of components, the boundaries and contexts of these compositions and the special conditions that should be guarded. All this can be expressed much faster in wireframe code, than in complicated text.

How should Kermit go about this?

To simplify I will focus on web application as the solution domain for Trotters. Kermit and the team are working with object-oriented (OO) design and development concepts, they standardise on UML notation. They could be programming on Java or .NET platform, that doesn’t matter here.

Here is a simple guidance for Kermit:

  • UML supports drawing component diagrams. Kermit has probably designed a layered architecture diagram. Therefore, Kermit can create equivalent UML artefacts in code by designing classes for relevant components using the most appropriate realisation path.
  • Components in a layered architecture will typically interact via interfaces. Kermit can create (mostly one-to-one) interface classes between each connection points in the architecture. OO design skills are necessary to do this right. This is a first test of Kermit’s ability to say it in code. This can be further refined when for example using a concept such as design by contract, of which ample free resources can be found on the Internet
  • Boundary conditions and constraints: modern programming languages like C# or Java offer an array of features to deal with constraints. (similar concepts are fairly trivial in other languages) In addition, boundary conditions and constraints can be expressed in test harnesses, in turn included in the codebase as part of a continuous integration setup. Such productivity measures are invaluable and they often teach teams aspects of the solutions that might not be trivial, let alone described in text documents.
  • Enforcing architecture: this aspect is made trivial when considering the development environments (IDEs) available to programmers these days. These IDEs ship (or can be complemented) with code analysis and validation tools. The most recurrent patterns and errors can typically be verified with little or no effort, thanks to the richness of the validation rules that are available for these tools. An organisation like Trotters, as discussed in part 1, is typically weak in this area, and that is a shame.

Once expressed in code, the following become enabled:

  • Efficient two-way feedback on the architecture: programmers can immediately spot any issues and raise them for resolution with the architect. Kermit’s ability to communicate in code will come in handy, as he is able to grasp implementation issues quickly and can improve his design in the process
  • Enforcing architecture principles: nearly every modern programming environment offer tools for validating code and testing boundary conditions.
  • Platform constraints are immediately brought to light: with architecture code, architects and programmers are immediately confronted with infrastructure constraints. This makes it possible to analyse the situation, convey feedback quickly to all stakeholders before anything is really built. This helps in reducing gaps in expectations across all groups.
  • Guarding against basic mistakes or repetitions: there are elements that are typically common to every solution in a given business domain. There is no value in painstakingly recreating such elements, as that would only expose Trotters to unnecessary mistakes (typing, errors or omissions due to human factors, learning the hard way).

An easy argument could be to claim that Kermit, as an architect, does not have enough time to delve into programming details. Another easy argument would be to claim that should Kermit delve in code, he would be overstepping his role (micro-managing?), or that the programmers’ creativity could be hampered. Such arguments are easy to bring up, it is very tempting when one knows nothing better to do. But such approach is misguided, in most cases. First of all, I argue that an architect can write solid code much faster than he/she can create useful documents with legible text and diagrams. A second reason why I think this is misguided, is that the tools and techniques available today are amazingly powerful and simple to use, not using them to their true potential equates to disservice to the organisation. As a way to illustrate this last point, I’ll take a totally unrelated example: as I look over the shoulder of some people using Microsoft Word, I’m often amazed to see how they go through the pain of manually formatting documents by inserting spaces and page breaks. These people don’t seem to be aware of features that were in the product since version 2.0! (the first I’ve used). That is the point. And this example is actually nothing compared to the inefficiencies caused by programmers and architects enforcing early 90’s work processes with 2010 generation of tools and techniques.

To summarise, if you can express architecture principles in diagrams and text, be sure to also express them in solid code to reduce communication gaps. I call this: say it in code. Users typically don’t relate to design documents (architecture is part of design in this context). Often case, design documents would pass approval gates without users noticing faults or shortcomings in them. And this should be expected, precisely because users hire architects for their solution skills and experience. Architects shouldn’t expect that users could validate solution architecture, which is what normally happens a lot – again I’m using the term users in a broad context here. On the other hand, once solutions are shown to users, they can more effectively provide meaningful feedback. So, Architects should express technical solutions in solution, and code is the closest form that can be less immune to human interpretation induce deviations.

So far, I’ve focused on the application architecture aspect of the Architect role, in my simplified view. Looking at the broader architect role, including business analysis and infrastructure design, saying it in code will involve other aspects that I won’t analyse too much here for a number of reasons. This posting is already quite long, I’m still trying to keep it short enough yet complete in its illustration. In future postings, I will tackle these other architect roles.

In the next instalment I will explore the limits of this concept. If I get more time, I will develop the concept further for Trotters by showing specific examples of the type of code that Kermit would be writing to help his organisation (eat your own dog food idea).

1 thought on “Information Systems Architect should write solid code, Part 2, how?”

Leave a Reply

Your email address will not be published. Required fields are marked *