Blueprints are abstractions used by architects and engineers to communicate the concepts and engineering elements through out a project design and implementation. Even more a floor plan could be used to prospect customers to decide into buying a new apartment. It is curious that engineers design blueprints to build skyscrapers that precisely tells the kitchen measurements on the 20th floor while end-customers are still able to walk through these documents and have insights. Furthermore, a layout has the following characteristics:

• At first glance one can tell what a blue print describes. It is easy to identify at high level if it represents a church, an apartment or a library.
• When usage is different then the blueprints are totally different.
• The usage is explicit. Large rooms can hold conferences and concerts while rooms with sink and oven describe kitchens.

Consider the following layout:

At first glance, one can guess that this picture represents a church or a concert room, this is absolutely not a house. Second, that the usage is explicit:

• Large entrance so dozens of people could enter and leave at the same time.
• Large room so a big group can gather together.
• Benches organized in the same direction.
• Welcome room for socializing.

Coming back to software engineering, could a document be useful to precisely implement software functionality and also be used as communication with stakeholders? Consider the following software architecture documentations:

UML Diagrams



UML diagrams are high level abstractions and each one show an angle of the software design. For instance a class diagram shows the objects relationships and structures while use cases describe actors affecting the system and its behaviors. High level design is subjective and lacks the necessary information to implement the software. Occasionally diagrams are outdated or ahead of time. This gap between the abstraction and the implementation is equivalent to the one found on code comments, they don’t tell the truth.

C4 Model

The C4 Model is an enriched diagram that uses layered view to visualize software architecture. It has four layers and starts with the System Context drills down into Containers, Components and Code. The relationships between these layers describe dependencies, data flow and intent. The Code layer expects an UML. The C4 Model tries to formalize the Box and Lines used by engineers to communicate software on last years and it promises tooling to keep the diagrams up to date with the codebase.

Source Code

Source code is low level and it is so strict that its syntax can be validated by a compiler. It shows algorithms, variables and methods names. Especially when programming on low level languages it is hard to express intent and usage, fortunately modern languages are closer to natural languages and allows engineers to organize concepts and show the usage in codebases.

Codebases

Codebases are the entire source code. Including filenames, assets, project organization and packaging. Everything from algorithms, tests and settings are part of it, for the better or worse the codebase is always telling the truth and is up to date. But why codebases are hardly used for communication with stakeholders? Could be one of the following reasons:

1. Business people lack the skills necessary to understand codebases.
2. Engineers are not proud of their codebases and they keep it for themselves.
3. Codebase’s pitfalls could scare even skilled software engineers.

To address the elephant in the room it is necessary to understand what are the codebase’s pitfalls. Consider the following:

• Rotten codebases happen when it grows without tests and guidance. Software was implemented just to make it work, bug fixing requires hours of investigation and are hard to reproduce. When walking through the codebase the engineer find spread business logic from different contexts mixed with low level coding and misplaced dependencies.
• Scattered codebases have a mixture of coding styles including coding convention and naming. Most important different designs fight each other. For instance pieces of software follow Object-Oriented principles while others follow Procedural Programming.
• Framework dependent codebases follows a rigid third-party structure. Sometimes these rules affect the way the business logic is designed, implemented and tested which slows down the development, creates vendor lock-in and obstacles to change the framework for a better solution if necessary.
• In addition to the previous characteristics, enterprise codebases suffers Conway’s Law, have rigid contracts and code smells that are repeated over and over again just to make every application look the same.

Documentation Comparison

The UML diagrams and the C4 Model lack the necessary information to implement the software, they are subjective and even using the best tools the engineer can’t tell if their diagrams are syntactically correct and complete. Tools can automate the synchronization between the diagrams and code, however a gap will exist. Second, an engineer design diagrams, add interactions, print them but they can’t run, test and deploy diagrams.

Source code and codebases have the necessary details to implement the software, they are objective, unambiguous and have the most advanced tools available to walk through the source code, compile, execute, test and deploy. On the other hand, there is long list of failed projects and rotten codebases that couldn’t showcase anything.

This article series is an attempt to show how codebases could describe software for engineers and stakeholders.

Software Architecture

The Software Architect’s challenge is to design a codebase that screams the use cases instead of the frameworks it uses. It sounds simple however most applications delivered over the Web scream HTML and Model-View-Controller. Other examples come from Pub-Sub systems where the code base screams Commands, Handlers, Events and Queries. Screaming usage is putting the use cases as a central organizing structure. Consider the rules of thumb:

• Decouple the delivery mechanism. When business rules and UI gets mixed up the necessary frameworks to build a fancy user interfaces takes over the codebase.
• Placed use cases higher in the codebase hierarchy.
• Implement use cases guided by tests (TDD outside-in).

To make it more clear see the next examples. It is expected that an e-commerce system shows the next use cases:

• Add to shopping cart.
• Order products.
• Track order.

A banking system would have at the top these use cases:

• Deposit.
• Withdraw.
• Transfer.

Frequent Misconceptions

To introduce Clean Architecture, first is necessary to define what it isn’t, consider the following misconceptions:

Less Source Code within the Business Logic Boundaries

Less code does not mean Clean Code especially when it came through the cos of frameworks in the business logic layer. The immediate benefits of frameworks does not resist the time and complexity of the business rules implementation, workarounds are needed when the coding conventions needs to change. Coding conventions reduce boilerplate code however it should happens on the User Interface and Framework layers.

Source Code Organized by Patterns and Categories

Second misconception is that Clean Architecture is a project where each pattern has a bucket. Something like put handlers in the handlers folder, messages in the messages folder. This is not Clean Architecture, suppose one is designing a building and putting all doors at the same place, all windows at the same place, it does not make sense.

Conclusion

Software Architecture has similar challenges as civil engineering. An architect that puts usage in priority will make a better design.

Stay tunned for next articles.