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).

Information Systems Architects should write solid code. Part 1, Why?

I believe that an architect, in the Information Systems world, should be first and foremost a very good programmer. The architect should write code on occasions, it would be better if writing code is actually a habit. When this is the case, the Architect is able to bring a positive influence to the organisation. When this is not the case, the Architect would most probably be less efficient and will find himself/herself regularly in unproductive discussions.

I believe that, in Information Systems environments, an architect should be first and foremost a very good programmer. The architect should write code on occasions, it would be better if writing code is actually a habit. When this is the case, the Architect is able to bring a positive influence to the organisation. When this is not the case, the Architect would most probably be less efficient and will find himself/herself regularly stuck in unproductive discussions. Unfortunately, a non-negligible amount of inefficiencies stem from the Architect’s lack of awareness of the application platforms and code and the engineering activities surrounding them.

This can be proven ab absurdo, but I will provide a simple case to illustrate the point.

In this and subsequent postings, I plan a multi-part posting, I will be using the term Architect to refer to anyone who has responsibility in capturing user requirements and translating them into instructions for programmers. This broad definition includes business analysts and application designers. Though infrastructure architects and designers play a key role in shaping up the IT environment, I will classify them as programmers in this discussion because they are often at the receiving end of something specified by someone else.

Those who have needs and ask for something to be done with the IS/IT systems are users.
Those who translate user needs into work instructions are architects.
Those who actually execute the tasks of creating or modifying IS/IT systems are programmers.
The expression write solid code designate the act of creating an artefact that can be unambiguously understood as machine code, when used in a modelling context these are formal model artefacts, when used in a programming context these are program source code.

I know there might be a million other definitions out there. I think, at this point, someone could take offence and quit reading. That would be too bad. I am not interested in definitions and titles, I want to make a point and I need these specific working definitions. They work fine in this context, take my word for it.

Let’s give a simple persona to our IS/IT Architect,  Kermit. Kermit is a man in his mid-thirties, he works for a company called Trotters Fresh Dairy Products  Ltd (known as Trotters).

Say that Kermit does not write code, whatever the reason. This means that Kermit is not familiar with coding issues because he doesn’t deal with them regularly (so Kermit actually knows a programming language? good for him, but he is not involved in coding at Trotters and that that’s the point here). Kermit only talks in concepts, not related to code.

Kermit communicates his concepts to the programmers Robert and Marie-Louise using diagrams and explanatory notes. Kermit also communicates with business stakeholders using diagrams and explanatory notes.

As software is written, there will inevitably be mismatches between the application release(s) and user expectations – malfunctions are particular kinds of mismatches, changes in user expectation are also forms of mismatches. Resolving any such issues involves representatives of users, programmers and architects. At the very least, Trotters IS/IT will be facing a number of challenges due to the combined effect of the following factors:

  • Kermit made his architecture decisions based on his extensive knowledge of widely used architecture frameworks and standards, papers from industry analysts and discussions in architecture communities, his own perception of what the business is about and what matters most to Trotters business and organisation
  • Kermit’s architecture was interpreted by the business according to their knowledge, their perception of IT and software (often shaped by external influences and people background), and their evolving needs
  • Kermit’s architecture was interpreted by the programmers according to their knowledge, the platform and programming tools they are using and the resources that were available to do the work.
  • Coding was constrained by a number of factors including technology platform, programming tools, resource availability, Robert and Marie-Louise are not aware of everything that might be possible with the tools in their possession. Some of Kermit’s suggested principles were not feasible due to these constraints, choices had to be made on-the-fly.
  • Changes constantly occur in Trotters’ business environment, with them people adjust their perceptions and their expectations, it is very hard to convey all those changes in a usable and timely manner to all stakeholders. So people make assumptions that they feel comfortable with and won’t necessarily validate such assumptions.
  • Business is always pressed for time, competition is fierce in Trotters’ industry, financial constraints are ever present, decision makers are dealing with compromises all the time

Arguably there is more to say about the factors that influence complexity in the organisation, the above seem sufficient to make the point here. Let’s analyse the impact of Kermit’s lack of awareness of the code:

  • Industry architecture best practices, analyst white papers, none of this make sense until they are cast into the reality of a specific organisation. This cannot be done efficiently without intimate knowledge of the platform and the way the application is being (or supposed to be) coded. With Kermit, Trotters organisation will be learning this reality casting process the hard way
  • Even if perfectly drafted, the architecture can quickly become stale because the business reality would have moved after Kermit issued his blueprints but before the applications could be fully built and released.
  • Kermit couldn’t coach Robert and Marie-Louise efficiently, because he wasn’t involved in the coding. Even if Kermit would work closely with the programmers, since Kermit can’t write solid code, then a significant amount of the programmers’ time would go into educating Kermit on coding issues and practices
  • The numerous micro-decisions made during the software construction contribute to a non-negligible change in the initial promises of the architecture, such changes will not surface until an application release is available to the users.
  • Kermit misses the chance of bringing any lessons learned back into his architecture vision, because the feedback loop is not present or is poorly executed. Conversely, Kermit has little or no way to ensure, thus guarantee, that his vision is actually been executed upon. If the vision wasn’t correct, that fact is not properly reflected everywhere. If the vision was correct but was poorly executed, there was nothing to prevent that from happening
  • Vendor platforms evolve, so any knowledge built on a particular set of vendor solutions is likely to become obsolete and require refreshing before it is put to use after a certain amount of time. This constant knowledge renewal typically doesn’t happen, sometimes because it cannot be afforded, but also partly because people tend to get stuck in their routines and fail to notice that their knowledge is becoming obsolete. There is nothing in place to validate that knowledge at Trotters’ is adequate and aligned between the architecture practice and the programming practice
  • Kermit probably know some technology platforms very well, but there is no telling that he knows the particular platform that is part of the solution at Trotters, or perhaps the platform has evolved since the last time that Kermit did any hands-on work on it.
  • Kermit cannot assess the experience of Robert and Marie-Louise on the platform either. Conversely, Robert and Marie-Louise have no effective way to find out about each other’s strengths and ensure they are complementary. Trotters’ organisation has to trust that things would work out somehow
  • Sometimes people do notice that their knowledge might no longer be sufficient, some could then become defensive and would fight to keep any blind-spots from the open. This is human, it can be fought but it should mostly be managed. Users, architects and programmers at Trotters are facing the same dilemmas, they might not even be aware that this could be motivating some of their actions.

We can go on and on about the factors that could be causing mismatches between user expectation and application releases, but the above is sufficient to derive a pattern and draw some preliminary conclusions.

When there is any significant distance between the architects and the actual solution building and delivery, inefficiency tends to creep in very quickly and organisations don’t get the most of their assets. It does not help when those who specify what needs to be done and outline how it should be done, are removed from the actual construction of the solution. When the architect has no idea what code was (or is being) written, he could be talking about concepts that only exist on his slides and documents but actually never materialised. What would be the point of that? The above is the rationale behind my statement that An IT Architect should write solid code.

In next settlements I will elaborate on how an architect could be writing solid code, increase his effectiveness in the organisation and ensure that his vision of the solution is as close as possible to the actual solution. I will call this Say it in Code.


I am an IS/IT Architect, I could be subject to the same shortcomings described above. This is one of the lessons that I have learned over time. I’ve always felt this to be an issue in my job, I try to minimise any gaps between the vision and the realisation that was made of it by staying close to the code.