I donāt even know where to start. Letās begin with this: If I donāt understand you, itās your fault. This has to be the most basic, fundamental principle of a good software architect (well, of any engineer), but most of the architects Iāve met so far, in many companies, donāt seem to believe in it. They donāt understand that the job of a software architect is to make complex things simple, not the other way around. They use diagrams, which are the most popular instruments of an architect, to explain to us, programmers, what he or she has in mind. But the diagrams are usually very cryptic and hard to digest. Whatās worse is that the complexity goes up in line with their salariesāitās disgusting.
Why is this happening? Why are their diagrams complex and difficult to read? Iām sure you know what Iām talking about; you probably have your own examples of such diagrams from projects and architects youāve worked with. So why do we have them?
Architects are proud of complexity, thatās why. They think that the more complex the problem theyāre working with, the better an engineer they are. Iāve had this dialog many times:
- You know, your diagram looks so complex ...
- Oh yeah, we're solving complex problems here!
Usually, after that, the architect smiles with an obvious feeling of satisfaction. Indeed, someone actually noticed how difficult his job is and appreciated his efforts. Someone is stupid, and he is smart. He can understand this multi-tier architecture, and I canāt. He definitely earns my respect, right?
Wrong! A good architect knows his main role is to decompose a complex problem into less complex components and let programmers solve them one by one. Just as a good project manager has to decompose a complex task into smaller ones. When the problem is properly decomposed (broken down into smaller, isolated and properly decoupled pieces), the complexity decreases, and it becomes easier for everybody to understand and resolve.
The main virtue of an architect is the ability to reduce complexity. Thus, a good architect would never be proud of a complex diagram. Instead, he would be proud of a simple and easy-to-understand drawing with a few rectangles that perfectly explain an entire multi-tier application. That is what is really difficult to do. Thatās where a true architectural mind shines.
There are not many architects like that. I canāt say Iām one of them yet, but I have a few recommendations for your diagrams. Read on and remember that the main goal of all this is to reduce complexity.
No More Than Five Rectangles. If you have more, there is something wrong. Try to explain yourself in less than five. Just group some of them together and give it a name. You donāt want me to spend more than a few seconds trying to understand who is participating in the show youāre presenting. I want to see them all at one glance and immediately understand who is who. I just made up the number five, but you get the ideaāmake sure all diagram participants are easy to count. Iāve seen diagrams with 25 or more rectangles ā¦ thatās unacceptable.
Use UML. Well, use whatever notation you feel comfortable with, but many years ago people agreed that instead of using different notations, it would be easier to learn one for all; thatās UML. Itās a huge format/standard/language, but you donāt need to know all of it. Just learn the basics; that will be enough to express almost any idea you have. I would recommend UML Distilled: A Brief Guide to the Standard Object Modeling Language (3rd Edition) by Martin Fowler.
Direct and Annotate Lines. There is nothing more annoying on a diagram than a line connecting two rectangles without any text on it and without any direction. Is it a flow of data? Is it a compile-time dependency? There are many possible meanings. Always use arrows, and always annotate themāthis will help me understand you much faster.
Donāt Use Colors. Or let me put it this way: Donāt abuse colors. And in order to avoid abusing them, you are better off staying away from colors in the first place. If you need to use colors, there must be something wrong with your diagram. Itās probably too complex; thatās why you need to use colors. Simplify it by grouping elements.
Donāt Be Creative. Itās not art; itās engineering. You donāt need to impress me; you need to deliver the message. Your goal is not to show how sophisticated your mind is. Moreover, your diagram style should not be personal. A diagram from you and a diagram from another architect should look almost exactly the same if they deliver the same message. Itās call uniformity. Thatās how you make them easier for me to understand. I donāt want to have to learn your personality in order to understand your diagram. If itās a server, draw a rectangle. Thereās no need to put a 3D picture of an HP server there. A rectangle is enough. Also, please no shades, no fonts, and no styles. Again, itās not an artistic contest. I will understand your rectangle pretty well without that āniceā shadow youāre tempted to drop. I will also understand an arrow with a default width; no need to make it wider just because your diagram editor allows you to. Donāt waste your time and my time on all this styling. Just focus on those simple lines, rectangles, text, and arrows.
As I mentioned above, the goal of all this is to reduce complexity and help me, a programmer, understand you, an architect. Remember, if I canāt understand you, itās your fault. Youāre a bad architect if you canāt deliver your ideas in a plain, simple form.
Sometimes the documentation and diagrams I create are too complex and difficult to understand because...
— Yegor Bugayenko (@yegor256) January 20, 2019
