Documenting Software Architecture

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned on Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

We learn how to code and we build some cool applications, and then we learn about architecture and how to make the application maintainable for several years…

However when we need to explain to someone else (new developer, product owner, investor, …) how the application works, we need something more… we need documentation.

But what documentation options do we have that can express the whole application building blocks and how it works?!

In this post I’m going to write about:

  • UML
  • 4+1 Architectural view model
  • Architecture Decision Records
  • The C4 Model
  • Dependency diagrams
  • Application Map
Continue reading “Documenting Software Architecture”
Advertisements

Reflecting architecture and domain in code

This post is part of The Software Architecture Chronicles, a series of posts about Software Architecture. In them, I write about what I’ve learned on Software Architecture, how I think of it, and how I use that knowledge. The contents of this post might make more sense if you read the previous posts in this series.

When creating an application, the easy part is to build something that works. To build something that has performance despite handling a massive load of data, that is a bit more difficult. But the greatest challenge is to build an application that is actually maintainable for many years (10, 20, 100 years).

Most companies where I worked have a history of rebuilding their applications every 3 to 5 years, some even 2 years. This has extremely high costs, it has a major impact on how successful the application is, and therefore how successful the company is, besides being extremely frustrating for developers to work with a messy code base, and making them want to leave the company. A serious company, with a long-term vision, cannot afford any of it, not the financial loss, not the time loss, not the reputation loss, not the client loss, not the talent loss.

Reflecting the architecture and domain in the codebase is fundamental to the maintainability of an application, and therefore crucial in preventing all those nasty problems.

Explicit Architecture is how I rationalise a set of principles and practices advocated by developers far more experienced than me and how I organise a code base to make it reflect and communicate the architecture and domain of the project.

In my previous post, I talked about how I put all those ideas together and presented some infographics and UMLish diagrams to try to create some kind of a concept map of how I think of it.

However, how do we actually put it to practice in our codebase?!

In this post, I will talk about how I reflect the architecture and the domain of a project in the code and will propose a generic structure that I think that can help us plan for maintainability.

Continue reading “Reflecting architecture and domain in code”

Architecture 1st design step: Partitioning

There are many ways of partitioning an application. Usually, what we do is actually classify the code according to some criteria and organise the code following that criteria.

This chapter of the book explores four criteria:

  • Functionality vs. Domain;
  • Conway’s Law;
  • Geographic constraints;
  • Cultural concerns.

All in all, the idea is that we partition our codebase with long-term local autonomy in mind, according to history, standards and conventions, experience and common sense (Coplien 2010, p.91).

Continue reading “Architecture 1st design step: Partitioning”

What is Lean and Agile about Software Architecture

Good Software Architecture embodies several Lean and Agile principles, always with the same goal of long-term productivity and lightweight feature development.

Delaying structural decisions will outcome in undisciplined structure, which in turn outcomes in waste. Therefore we must think of Software Architecture as an investment that we need to make now to get medium and long term gain.

Continue reading “What is Lean and Agile about Software Architecture”

Stakeholder engagement: Trimming wasted time

In my previous posts, I briefly described the stakeholders. However, they are not Lean nor Agile themselves. What is really important, for Lean and Agile, is how they work together: Everybody, all together, from early on. Continue reading “Stakeholder engagement: Trimming wasted time”