I was watching Simon Brown’s Frustrated Architect presentation and I found it an interesting trip through design approaches and artefacts. Although slightly irritated that some of the agile approaches seemed to be exaggerated for effect (although I admit that there are some really bad software development teams out there calling themselves agile), his conclusion was what I expected in that you choose the right tool for the job. I think that his point is well made that some software developers are probably now unaware of some of the notations and mechanisms used over the past 10-20 years as these are considered historical relics in some parts of our amnesiac industry. I also agree that these notations and mechanisms still have legs even in the world of agile software development and I’ll explain why.

At a simple level, I like diagrams since they can often be understood by  people with different skillsets (for example non-code readers). They can also represent concepts at different levels of abstraction not just code-level constructs. Even amongst people who could potentially sit beside eachother at a keyboard and TDD the life out of a problem, diagrammatic notations allow for potentially quicker exchange of ideas as they are easy to draw up on a whiteboard. Finally, the diagrammatic notations provide a more compact way of conveying the same information you could potentially find in the code and the use of shapes and patterns can make it easier for our pattern-recognising brains to spot inconsistencies in the relationships. In all of these example uses you may have noticed one thing: they are always being used as a collaboration tool rather than being captured in a static document to be bounced back and forth over email or referred back to as the one source of truth. Diagrammatic notations, like the code they can spawn, should be transient artefacts that are refactored as understanding evolves and retained only if they are still useful at any given point.

The discussion of different notations also put me in mind of the time I was writing a set of patterns with Paul Dyson. We workshopped these patterns for several years at EuroPLoP and they eventually came out in book form. Naturally we worked hard to ensure that the patterns were technically correct but we also put a lot of effort into ensuring that the content was logically consistent. Patterns, by their very nature, draw out a balance of the forces at work within them and their form also has a natural rhythm and flow. There are various different forms for patterns such as GoF style, POSA style and Alexandrian. The GoF and POSA formats tend to be more structured and lend themselves to more technical patterns such as those at the code level. Alexandrian form is that used by Christopher Alexander on his building-related patterns and consists of a more fluid prose but with a structure still woven into it.

The patterns that Paul and I were writing were not code-level patterns but essentially system-level patterns with a good dose of infrastructure thrown in. At first, when we created the patterns for workshopping, we wrote them in something close to POSA-style with very separated sections. However, when we came to work on them for the book, we decided to re-write them in Alexandrian format to see if that worked better. The interesting thing was that as we did this, we noticed that some of the patterns had inconsistencies and missing elements that had not shown up all the time they were being shepherded and workshopped in their POSA-like form. The very act of swapping between the two pattern formats had highlighted issues we would not have spotted in the original form (an no doubt the same would have been true if we had started with them in Alexandrian form).

This brings me back to the question of “old-style” notations compared to the coder’s eye view which is common in agile. Although in software development the code is ultimately the most important artefact since you cannot deploy a CRC card or UML model, it only provides one view on the system being created. Modelling parts of the system in different notations can give you insights that you might otherwise not have encountered and can potentially enrich the code that is eventually delivered. Naturally, this benefit is not without cost as there is more effort in effectively modelling the same things twice, but you would not do this for everything in the system or at particular points in the system lifecycle. Paul and I only re-wrote the patterns when we were moving them into the more permanent format of a book. In the case of building a system you might do this exercise for key parts of the system and just stick to a code-only view for less critical parts.

To slightly adapt the approach of the agile manifesto, while we all recognise the value of well-written and well-structured code there is also value in diagrams and notations that we may create to help us understand the concepts it contains.