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”

16. No silver bullet

This post is part of a series of posts with my personal notes about the chapters in the book “The mythical man-month” by Frederick P. Brooks. I write these posts as I read through the book, and take notes on the concepts I find more relevant. I do, however, advise reading the book to get the full benefit out of it.

This chapter was added to the 20-year anniversary edition of 1995 and is a transcript of a paper Brooks wrote back in 1986 titled “No Silver Bullet – Essence and Accident in Software Engineering“, which won him the Turing award, often described as the “highest distinction in computer science” and “Nobel Prize of Computing”.

In it, Brooks addresses the essential tasks of building software and suggests:

  • Exploiting the mass market to avoid constructing what can be bought;
  • Using rapid prototyping as part of a planned iteration in establishing software requirements;
  • Growing software organically, adding more and more function to systems as they are run, used, and tested;
  • Identifying and developing the great conceptual designers of the rising generation.
    Continue reading “16. No silver bullet”

15. The other face

This post is part of a series of posts with my personal notes about the chapters in the book “The mythical man-month” by Frederick P. Brooks. I write these posts as I read through the book, and take notes on the concepts I find more relevant. I do, however, advise reading the book to get the full benefit out of it.

Documentation is needed.

Others need to understand what our application is, what it does how it does it, how it behaves. The application code, as well, needs to be understood, not only by the machine but also by the next developer reading it.

We need to document all the way from a faraway view of the system to a detailed view of the system.

Then the question is: What and how to document?
Continue reading “15. The other face”

14. Hatching a catastrophe

This post is part of a series of posts with my personal notes about the chapters in the book “The mythical man-month” by Frederick P. Brooks. I write these posts as I read through the book, and take notes on the concepts I find more relevant. I do, however, advise reading the book to get the full benefit out of it.

Plenty of projects, if not the vast majority, end up getting delayed… Some more than twice the initial estimated time and cost. This happened up until 1986, when the book was published, but it still happens today. I feel it is, sadly, very common.

But how does this happen?

How can we prevent it?
Continue reading “14. Hatching a catastrophe”

13. The whole and the parts

This post is part of a series of posts with my personal notes about the chapters in the book “The mythical man-month” by Frederick P. Brooks. I write these posts as I read through the book, and take notes on the concepts I find more relevant. I do, however, advise reading the book to get the full benefit out of it.

Curiously enough, Brooks starts this chapter by mentioning something I say every once in a while:

The challenge is not simply to build something that “works”. It is to build something that really works in the way the end user needs it to work, with conceptual consistency, minimal technical bugs, and that can be maintained and extended throughout a long life.
Continue reading “13. The whole and the parts”

12. Sharp tools

This post is part of a series of posts with my personal notes about the chapters in the book “The mythical man-month” by Frederick P. Brooks. I write these posts as I read through the book, and take notes on the concepts I find more relevant. I do, however, advise reading the book to get the full benefit out of it.

The work quality and efficiency of a crafter depends a lot on the tools at hand.

In this chapter, Brooks makes a case for this statement validity for software developers as well and gives a list of essential tools needed for software development.
Continue reading “12. Sharp tools”