Software Architecture Diagram Types

I am moving the blog to https://sixro-on-software.blogspot.com/.
In the next months, I will close this one.

In this article, I’ll try to explain some software architecture diagram types. This will not be a comprehensive guide of all the types of software architecture diagram available, but I hope that it will help you in representing the architecture of your software.

What is a software architecture diagram?

First of all, we need to make clear what a software architecture diagram is: simply put, it is a representation of how things work in a software.

There are a lot of ways to represent a software architecture. I know 3 ways to do it:

  • Conceptual Architecture Diagram
  • UML Diagrams
  • C4 Model

Conceptual Architecture Diagrams seem simple, but they are not. Basically, they represent the “big picture” of a software/system. Looking at it, the reader can immediately grasp how things work even in a very complex system.

UML (Unified Modelling Language) is really big (and probably this is the reason it is not used so often), but with just one or two diagrams we can do a great job in explaining our software architecture. Even today, when I need to explain how things work in a software, I draw an improvised Communication Diagram. In this way, I can give immediately an idea of the components, the relationship between them and how they interact each other. I am not a fan of Sequence Diagrams because I find they promote “procedural code” instead of allowing me to create “OO code”, but they are effective too (and by the way that was another story :D). In the last 10 years, I used just those 2 diagrams and sometimes the Use-Case Diagram. I don’t see a Class Diagram since 2005 and never seen used any of the other diagrams.

C4 Model is the most recent one. It represents the overall architecture using multiple views of it.

  1. Context diagrams: show just the systems and the relationship between each other. It gives you the “big picture”
  2. Container diagrams: decompose a system into containers (e.g. an application, …)
  3. Component diagrams: decompose a container into components, and relate the components to other containers or other systems
  4. Code diagrams: provide details about the design of a single component

To me, it seems an improvement of an old diagram called 4+1 architectural view model.
I have never used the C4 Model, so I won’t talk much about it, but I am pretty sure that combining a Conceptual Architecture Diagram with others diagrams mentioned in UML, you can reach almost the same result provided by C4 Model.

What should be included in software architecture diagram?

In a software architecture diagram, what you should include depends on the diagram and the type of diagram to choose depends on the audience.
Here some examples of what you should include.

This is an example of a Conceptual Architecture Diagram:

Conceptual Architecture Diagram

As you can see, at the center you have the core software mentioned as “Security Manager”, while on the edge you can see “external” parts such as (in this specific case) languages (on top left) that could use the software, databases (on the bottom), LDAP, etc… In the center, the software is composed by internal blocks that are shown in order to give the reader an idea of what the architecture contains. You can see also some interaction between some internal components and external parts (for example the arrows between “Cache” and the RDBMS) that could be used to reason implementation details worth to mention.

The following diagram is an example of Communication Diagram (that in older versions of UML was named Collaboration Diagram and even today you can find it with this name):

Communication Diagram

This diagram can be found on uml-diagrams.org (I suggest to take a look to that website, because it is really good in explaining UML).
The example contains a lot of blocks, labels, colors, etc…, but just to make things really simple, you have to remember one thing in order to draw a good Communication Diagram:

draw the main components of your software as blocks and connect them specifying also the sequence of execution

That’s it. Pretty straightforward. I never have the need to make it tool complex. Also because, if it becomes too complex, it means 2 things:

  1. you are explaining too many details
  2. your design is really too complex

For 1. I have one tip:

when you draw the components, this doesn’t mean that you have to draw all objects used by your software to work. You can draw just the main components. Leave the details to the code or to others diagrams (e.g. the Sequence Diagram, the Class Diagram, etc…)

For 2. pay attention, because sometimes a Communication Diagram can give you some hints on what is wrong in your architecture: maybe you can see in front of your eyes that there is a component that is not needed. On the other side, sometimes when you translate in code a design made on paper, it won’t work because coding is a totally different beast.

The last example is a Sequence Diagram:

Sequence Diagram
Sequence Diagram

This is a very simple Sequence Diagram, but it is good for explaining how it works.
On the left, you can see the operation checkEmail called on Computer. When this happens, Computer calls sendUnsentEmail of Server. After that, it calls newEmail of Server waiting for a response. The next steps can be read by the reader as an exercise.

I have always considered Communication Diagrams more maintainable when compared to Sequence Diagrams, if you like to draw them by hand. But nowadays, there are a lot of free software to draw Sequence Diagrams that can be updated in a couple of seconds (I’ll mention them in the next paragraph).
One thing that I noticed in my career is that, when people asked to see a Sequence Diagram of a piece of code, I could bet that the code was full of code smell or unmaintainable or unexpectedly complex πŸ™‚

How to draw a software architecture diagram?

In order to draw a software architecture diagram you can use some software freely available, but I’d not refuse to draw them by hand. For example, I liked to draw a communication diagram while explaining the architecture of a software to a new team member.
In the next paragraphs, I’ll mention some free software I found pretty simple to use:

diagrams.net (online): it was known as draw.io few years ago. It is really good to draw all software architecture diagram types, but I’d use it mainly for Conceptual Architecture Diagrams and Communication Diagrams.
For Sequence Diagrams I found alternatives that are far simple than diagrams.net

Dia (installation): I would say that with Dia you can probably create any diagram. Really. If you look at the screenshots section of the website, you’ll see that I am telling the truth πŸ™‚

Violet UML editor (Eclipse plugin): I used this in the past as an Eclipse plugin. I remember it was doing a good job, but I never had the chance to try it in my last job (so almost 7 years :D). I cannot give any feedback about the more recent versions.

ArgoUML (installation): I used ArgoUML a lot in the past. It is really good. You can write all UML diagrams with it. It is available since 1998… more than 20 years! The link I put is the Github project so that you can then find the right way to install it on you computer.
The UI is made with Java (I think Swing) so it can work on any desktop.

In conclusion

There are plenty of software architecture diagram types.
Choosing the right one is a matter of audience.
Non-technical people will be glad to view a Conceptual Architecture Diagram of your software. Technical people will be glad to view a Communication Diagram (or a Sequence Diagram) in order to understand how it works.

The steps to create a software

There are just 2 steps to create a software: creating it and checking how it goes.
If you came here to know something about Systems Development Life Cycle (SDLC), I can guarantee you that the relationship between that thing and the real world is basically non-existent.

Oh Come on! And what about requirement analysis, design, etc…?

They exist only in the mind of an accountant/project manager.
They are artifacts created to add more items to the list presented to a potential customer during the software quotation “dance”.

There is no analysis. Or put in a different way, while you create a software, you are continuously thinking/analyzing if what you are doing is the right thing.
For the pragmatic reader I am showing what happens in the real world:

SDLC PhasesReal world
InitiationCome on
System concept developmentAre you kidding?
PlanningManagerial stuff(*)
Requirement AnalysisCreating
DesignCreating
DevelopmentCreating
Integration and TestCreating
ImplementationCreating
Operation and MaintenanceHow it goes
Disposition(How it goes?) Not so well

(*) You’ll do anyway some planning, but leave that Gantt to your PM friend

We already know this: it is iterative… or incremental? Yeah, but I know it!

Image taken from Wikipedia

In my mind it has never been iterative. Probably chaotic is the right word. Fixing that chaos in my mind is the thing that made me want to study how to write a “successful software”.
I think “iterative” and “incremental” are pretty words chosen carefully to explain to an old man a new way to manage a software, but changed very little to someone who spent its life in writing software for real. People were not happy with the waterfall approach as much as they are not happy with anything else that does not allow their mind to create what is needed.

Did you hear about Kanban…

I didn’t apply Kanban in my career, but I know that Scrum is really difficult to apply.
When badly applied, that creative process is interrupted and your software start to become a secondary thing after all the rest.
I am pretty sure there are other ways to align a team if that is what you are looking for.

In summary

If you have to write a software, just create it and see how it goes.
If you have to write a software quotation, I fill your pain.

The abuse of object factories

Recently I found this smell: the abuse of object factories.

Usually, there is already another smell: you are using DTOs.
Do not try to fake it removing “DTO” from the name. Instead, please read β€œLet the domain drive” architectural pattern and save yourself from a life of dumb conversions
You need to create it with some domain objects involved.
And… now… you have an object factory.

I rarely use object factories, because usually the constructors or a factory method are enough.
I use these rules:

  • if I am creating an object at the edge of the hexagonal architecture and I realise that I need to create it just “manipulating data” from other domain objects (and again… lots of smells here), a factory method or a constructor should be enough.
    Then, if a test gives me the feedback that I cannot proceed with that solution(*), I’ll move to an Abstract Factory design pattern (or a more simple object factory)
  • if I am creating an object at the same level(**) of others needed to create it, sometimes I use the previous rule, while sometimes I ask to one of those objects to transform itself in the one I need (such as Java does with that toString)

I know that this is a basic/simple topic, but it can reduce significantly the number of objects in your application. Recently, applying this “tecnique”, we reduced the number of objects in a package from 13 to 8. Not a big improvement, but the code is definitely more simple to read and change.

(*) for example, due to the number of collaborators involved, etc…
(**) “same level” means that you have all domain objects or all objects at the edge of the hex arch

“Let the domain drive” architectural pattern

One of the most helpful concept I learned in my career is the Hexagonal Architecture.
I started using it in green-field projects and I was very happy with it.
After years, I changed my job and went in a so called “agile” company.
Some projects were in a very bad shape… but also new projects had something weird.
And the funny thing was that people working on those new projects were telling me that they were using the Hexagonal Architecture.
WHAT?
They were right: the Hexagonal Architecture was there… but I didn’t recognize it. And the reason was that it didn’t match my style!

Basically, what I found was that:

  1. sometimes the domain objects were not “mentioned” on ports: there were other objects… a kind of anti-corruption-layer (ACL) in between the domain and the ports
  2. the adapters had new objects equal to the domain ones, but not totally… they had some differences here and there… and there were mappers between the domain objects and those duplicate objects
  3. the domain objects were highly protected by “everything”. They were living in a specific module. The adapters were in another module with their objects very similar to the domain ones. If you have to add something to domain objects you were pretty sure you’ll have N other changes to apply (where N is the number of ports in your software)

In the future, I’ll share some techniques we used to refactor those applications.
But in this post, I want to share an improvement to the Hexagonal Architecture that add an additional principle.
I think this architectural pattern is already known by expert OO programmers… probably it is obvious for them, but it has no name, it is not mentioned, and lots of colleagues (even experts not only novice or advanced beginners…) create architectures with the issues mentioned above, so… I decided the name πŸ˜€

It’s called “Let the domain drive” architectural pattern.
The added principle is: “if you have to share the state of an object, you strive to share it without polluting your application with duplicated objects”.
Does this mean that your domain objects are in trouble?
No, when you realize that they are in trouble because of “external influences” that could make them “dirty”, you can act duplicating objects… but you have to be sure you need it (YAGNI).

How to handle the known issues mentioned

Now I’ll look at the findings mentioned above and I’ll try to explain how to handle those issues with this architecture.

Issue 1: domain objects not used in ports

This is simple.
It is an error even if you are using the Hexagonal Architecture.
So, please fix this.

It seems someone around the world think that you can have DTOs in the ports.
Just as an example, here you can find an article by Matteo Vaccari on the The Birthday Greetings kata. Do you think it’d be acceptable having the EmployeeRepository returning a List<EmployeeDTO>? Why not the List<Employee>? Employee is the domain object here. Why do you need to use that DTO? Do you have a reason? if the reason starts with “because if in the future…” STOP: YAGNI

Issue 2: adapters with objects very similar to the domain ones

In the “Let the domain drive”, you strive for having only and only the domain objects. Objects that are similar to the domain ones should be used only if you are already sure that the state of your domain objects cannot be “shared” externally.
If YAGNI, you stick with just your domain object.

Issue 3: touching 1 object requires N other objects to change (where N = ports)

In the “Let the domain drive”, you remind yourself being a software engineer.
With this in mind, when you realize that there is a repetitive task/action… a common pattern… something that could become a “liability” in the future, you start applying different techniques to handle automatically those things.

For example:

  • Storing objects automatically using reflection
  • Creating new “objects”/”map”/”things to share with external systems” automatically using reflection or “describing how” in the domain object using syntactic metadata (e.g. Java annotations)
  • Generating code

Everything is allowed if you are not polluting the domain objects with “technical stuff” at the same abstraction level of “domain stuff”.

Just to give you an example found for real (I changed just names). If you have a domain event such as:

public final class ProductPurchasedEvent extends EventObject {
private final Product product;
private final Price price;
[...]

}

and you have to store the event in JSON, you could create new objects ProductPurchasedEventJson, ProductJson, PriceJson and make the mapping manually. This approach is not consistent with Simple Design and by the way it costs a lot in maintenance!
Repeat this approach every time you have this kind of problems and you have just confirmed that you are not a programmer, but a creator of liabilities in your company.
Your company should sue you… just joking (or maybe not).

In the “Let the domain drive” architecture, at the beginning you’ll try to “serialize” the entire object in JSON. Then, if you realize that you can share only parts of the state of your domain object you could add Java annotations to prevent sharing everything or maybe you already have parts of the object that should have been marked as transient

Remember that you are an engineer.
And I am pretty sure you’ll find a solution for your specific case.

What does “Drive” word stands for?

We talked mainly about technical stuff, but “Let the domain drive” architectural pattern is a matter of creating a product with a simple design.
So the real job starts when you have to evolve an object that is in trouble because someone is going to mix data with different meaning in the same place (such as technical data with domain data).

I am going to give you an example. Imagine that you have a domain object representing a product purchase. You mapped automatically that product purchase from a payload of a REST call. Now they need to put a trace id of the HTTP request. If they put that trace id in the payload, your domain object will be in trouble.
So:
you suggest to use a different place to put that trace id, such as (for example) the HTTP header.

This is how you use that “Drive” word.
Your architectural decisions are handled in order to keep the design simple without polluting the application with useless objects and without mixing data.
This is a very simple example, but it is because the entire idea is simple.

What if someone forces you to put that trace id in that payload?

Then, it is time to protect your domain object, but I’d share with the people forcing you that your project will start to cost a little bit more than the solution you suggested. And I’m not joking! It will cost more for sure!

PROS of “Let the domain drive” architectural pattern

  • You’ll have just one object to represent something with just one name (more symmetry and consistent with the 4th element of simple design)
  • You’ll be fast in embrace changes (reduced costs of changes)
  • You’ll understand the code better and faster (clean code)
  • You can apply it even on legacy code, because you have to accept different approaches for each domain object…

CONS of “Let the domain drive” architecture

  • You have to protect your domain objects. If you have junior programmers (or programmers that are not really “clean”), they won’t realize when it is time to break the usage of this style because it is no more suitable
  • Watch for over-engineering. As an example: I have seen people starting with a simple system to store objects automatically on DBs ending with a kind of home made Hibernate or a home made Spring Jdbc. You should remind yourself that the solution should be cost effective
  • You could have different approaches for your objects. Maybe an object can be shared automatically and another one requires a manual mapping. I met people that rather prefer to use the same approach everywhere instead of reducing the duplicated objects.
    If this kind of situations, you’ll have difficulties with this architectural pattern.
  • When a programmer uses this architectural pattern, he’ll have difficulties in going back to the previous approach. His life as a programmer will be ruined πŸ˜€

Remember: the aim of this architectural pattern is not to have “a standard way to approach *any* design or every part of your design”, but to stay as much as you can with your domain objects in every part of your application, “disconnecting from them” only when you really need.

Show Your Work! Book Review

Book cover

Recently I read a book called Show Your Work!: 10 Ways to Share Your Creativity and Get Discovered by Austin Kleon.
My blog is about the things I like the most such as software design, technology, self-improvement, …
The reason I started again writing my blog is the messages found in this book, so I want to share with you some highlights I took from it…

Following I share parts of the book I found really interesting.

Genius? No thanks: Scenius

There are a lot of destructive myths about creativity, but one of the most dangerous is the “lone genius” myth: An individual with superhuman talents appears out of nowhere at certain points in history, free of influences or precedent, with a direct connection to God or The Muse.

Chapter 1. You Don’t Have To Be A Genius

There’s a healthier way of thinking about creativity that the musician Brian Eno refers to as “scenius”. Under this model, great ideas are often birthed by a group of creative individuals […] who make up an “ecology of talent”. If you look back closely at history, many of the people who we think of as lone geniuses were actually part of “a whole scene of people who were supporting each other, looking at each other’s work, copying from each other, stealing ideas, and contributing ideas”.

Chapter 1. You Don’t Have To Be A Genius

Here the idea of Scenius was really meaningful to me.
I’m the one used to think that some ideas I have are not so important to be shared.
But if you think to the meaning behind “Scenius”, those ideas can matter to someone in this world. It is important to share them, like an amateur would do it.

Amateurs are not afraid to make mistakes or look ridiculous in public. They’re in love, so they don’t hesitate to do work that others think of as silly or just plain stupid.

Chapter 1. You Don’t Have To Be A Genius

The world is changing at such a rapid rate that it’s turning us all into amateurs. Even for professionals, the best way to flourish is to retain an amateur’s spirit and embrace uncertainty and the unknown.

Chapter 1. You Don’t Have To Be A Genius

You have to find your voice.

We’re always being told find your voice. When I was younger, I never really knew what this meant. I used to worry a lot about voice, wondering if I had my own. But now I realize that the only way to find your voice is to use it. It’s hardwired, built into you. Talk about the things you love. Your voice will follow.

Chapter 1. You Don’t Have To Be A Genius

It’s not about Perfection

Don’t worry about everything you post being perfect. Science fiction writer Theodore Sturgeon once said that 90 percent of everything is crap. The same is true of our own work. The trouble is, we don’t always know what’s good and what sucks. That’s why it’s important to get things in front of others and see how they react.

Chapter 3. Share something small every day

I don’t have much to say about this sentence.
It is just a reminder to me… to my “if it’s not perfect it’s not worth it” brain.

Find Inspiration

“Dumpster diving” is one of the jobs of the artist – finding the treasure in other people’s trash, sifting through the debris of our culture, paying attention to the stuff that everyone else is ignoring, and taking inspiration from the stuff that people have tossed aside for whatever reason.

Chapter 4. Open up your cabinet of curiosities

Reading other blogs and books is what I do.
Lots of what I write is inspired by them or things I tried and worked (or did not worked).
Sometimes I don’t remember where I read something, but when I do, it is important to credit the work of the others.
Austin reminds this to us…

Crediting work in our copy-&-paste age of reblogs and retweets can seem like a futile effort, but it’s worth it, and it’s the right thing to do.

Chapter 4. Open up your cabinet of curiosities

Tell a story

Most story structures can be traced back to myths and fairy tales. Emma Coats, a former storyboard artist at Pixar, outlined the basic structure of a fairy tale as a kind of Mad Lib that you can fill in with your own elements: “Once upon a time, therewas __________. Every day, __________. One day, __________. Because of that __________. Because of that __________. Until finally, __________.”
Pick your favorite story and try to fill in the blanks. It’s striking how often it works.

Chapter 5. Tell good stories

This is how I wrote Once upon a time… in Objectsland.

Teach something you learned

The minute you learn something, turn around and teach it to others. Share you reading list. Point to helpful reference materials. Create some tutorials and post them online. Use pictures, words, and video. Take people step-by-step through part of your process.

Chapter 6. Teach what you know

This sentence drove me to start writing about things I know about projects I worked on or about teams I worked with in the past years.
And again…

When you teach someone how to do your work, you are, in effect, generating more interest in your work. People feel closer to your work becaure you’re letting them in on what you know.

Chapter 6. Teach what you know

Learn, learn, learn…

You can’t be content with mastery; you have to push yourself to become a student again. “Anyone who isn’t embarassed of who they were last year probably isn’t learning enough” writes author Alain de Botton

Chapter 10. Stick around

Thanks Austin.

Few words on the 4th element of Simple Design

The 4 elements of Simple Design

Suggestions to young men

Few days ago I made an interview.
The interviewer (Tommaso Torti) asked me if I have suggestions to give to young men starting a new career in software development.
Just as a recap, I mentioned:

  • find a company with high skilled software developers
  • changing job frequently: for example every 2 years
  • after few experiences, remain a little bit longer (5 years?) to find how good your design decisions have been in the long term
  • read classics: not only about software design… I mean also The Mythical Man-Month by Fred Brooks, Peopleware by Tom DeMarco, etc…

A missing point

But I forgot to mention one of the most important point.
In my opinion, to become a real expert in Software Development (not only OOP), you have to spend a lot of time on the 4th element of Simple Design: minimal methods, classes and modules (also known as “fewest elements”).

I know it sounds silly: “ehi man, I am already writing the minimal methods, classes and modules!”
Maybe! But, maybe not!
How do I know?
2 reasons:

  1. I have seen code written by lots of people. Expert people. Very often, I could have written the same code with half of the objects/methods/modules maintaining (or even increasing) the readability of the entire code base
  2. I found people able to write the same code I wrote, with a reduced number of objects/methods/etc…

So yes, it is a virtuous “mechanism” that once established creates an “obsessive” research on “how to write less, keeping high readability”.

What happens in reality is that, Object Oriented Programmers are focused mainly on SOLID principles, on the first 3 elements of Simple Design and don’t give any attention to reduce the things they write.
This is the reason I wanted to say few words on the 4th element.

A story

I have a story to share with you.
In my company, we had a coding exercise as an entry test for every applicant: Sales Taxes (you can find my solution at that link).
As an interviewer, I have seen lots of solutions and I can tell you that the majority of applicants created a solution with more than 30 objects. Some of them, reached more than 50 objects. I remember one guy proposing a solution with more than 80 objects.
Few people used 10 objects or less.
I haven’t seen all solutions, so I am talking just about what I have seen.

Another aspect: some developers wrote a solution with lots of objects that could adhere perfectly to SOLID principles and to the first 3 elements of Simple Design. Other developers wrote with fewer elements, but with procedural code.
I can tell you this: I accepted solutions wrote by the latter more often than by the former.
The reason is that, it is very difficult to train yourself on writing less. I think it is almost impossible to train on production software without a mentor helping you, unless you are naturally “obsessed” on this topic.

It is all about “simplicity”

There is another reason I think the 4th element is important.
If you are an object oriented programmer, you are naturally inclined to organize “things” (objects, methods, etc…).
But, as mentioned in The Laws of Simplicity by John Maeda, there are a lot of other ways to create simplicity and the first one is called “REDUCE”.

How to improve

Assuming that you want to train yourself anyway without a mentor, I can share some “exercises” you can do in your daily job or in some pet project you have:

  • try to start with just one module: you can add more modules later. If you really need them (and probably they will be created with a different idea behind them)
  • try not to duplicate your domain objects due to your adapters.
    For example when you have a domain object and then you have another DTO for the REST adapter, one for the persistence, another one to call your supplier, etc…
    If you really need this solution, try to avoid at least a hierarchy of mappers to create those objects from domain ones and vice versa: put factory methods in those objects instead
    Anyway, did you try with just data mappers and Maps? Sometimes, the idea that you need another object lies only in your mind…
    Did you try using reflection with some project convention?
  • try to count the objects (or methods) you are creating for a new feature.
    Put a label near each one: NEEDED, MAYBE, USELESS
    – USELESS: you should delete them immediately
    – MAYBE: “maybe” you can do something to make them USELESS
    – NEEDED: maybe you can think again… once more… are you sure? If you really think they are NEEDED, leave them alone
  • avoid “extract method” to have then just a private method containing one call to a collaborator. It does not increase readability at all! Change the name of your collaborator instead (or of the method name called)
  • pay attention to Parameter Objects. The idea that you need a Parameter Object when you have more than n parameters is the most stupid thing I have ever read (if you think this call discount(Product, Price, MarketStrategy, Report) is less readable than discount(DiscountRequest) you’ll be in trouble reading my blog). Besides, Parameter Objects often hide domain objects in the primitives used (I wrote a story about this: check Once upon a time… in Objectsland).

If you want to share another training exercise, please write a comment below.

I hope you’ll find interesting to spend some time on this aspect of software design.

Once upon a time… in Objectsland

where only objects with a meaning are admitted

"Spiral Jetty" by Robert Smithson
“Spiral Jetty” by Robert Smithson

Once upon a time, there was a place called Objectsland.
Every day, objects were living their life, working together, forming new collaborations.
The city was continuosly growing and flurishing.

One day, Necromancer Techcoacho Ignoranto arrived in the city.
He had to deal with all the objects in the city.
Soon, he became scared. He didn’t want to deal with so intelligent objects.
He’d have want objects without a brain, so that he could control them.
The other objects would have not left him doing that, so, one night, he decided to cast a spell mentioned in ancient books of refactoring: “Parameter Objectorum!!!”

The day after, Objectsland seemed as before, but after few weeks new objects arrived… they were like buckets of texts, numbers, … and they were a lot… they were: the Parameter Objects! uhuhohohahahahahahah

One day, one of this Parameter Object was filled with a text girl called Airline and a boy called Flightnumber.
Airline was in love with Flightnumber, but she was just a lonely text and he was just… a number (e.g. 89)? or a text (e.g. “0089”)? he didn’t know…

Since the arrive of all those Parameter Objects, the life in Objectsland became difficult. You had to deal always with them for everything and they were so many that you didn’t know who was in charge of something.

One day, a mage arrived in Objectsland. He was called Oldoop Pragmatico.
Looking at the poor Airline walking alone far from Flightnumber, he decided to step in! Immediately, he cast the powerful spell: “Ubique Dominatum!!!”

Since then, no one has seen a Parameter Object.
Eventually, Airline married Flightnumber and they decided to form a family: they called themself FlightDesignator following the suggestion of IATA Guild.

All the free objects decided to put a signboard at the entrance of the city.
This is the message:

Welcome to Objectslands where only objects with a meaning are admitted.
For data buckets, DTOs, etc… please follow the other street.
It will lead you to Wasteland

A note for Software Engineers:
yes, I’m arguing that ParameterObject is an antipattern that will get you to MagicContainer sooner or later.
It’s just a matter of time.

I have been interviewed

I have been interviewed the past Friday (2020-07-17) by Tommaso Torti.
You can see it at this link. Unfortunately it is in italian, so…

The title could be translated to “Inside the mind of a team leader”.
I talk about my experience as a team leader in a period starting from 2015 to 2019 (I’m not a team leader at the moment due to management decisions), but I touch experiences I had as a technical leader, software developer, etc… in my whole career.

I hope you’ll enjoy it.

The most important convention lies in your build system

The conversation

rick: “OK, good, it seems the build is successful! So we can create the merge request and eventually release the software in production!”
john: “No, wait… you need to push on git and then wait for the pipeline on Gitlab”
rick: “oh ok. Let’s push the changes. (wait some minutes for the pipeline). OK, the pipeline is ok… so now we create the merge request!”
john: “Yes sure… (after some time for the code review)… “
rick: “OK the branch has been merged, so now I think we can release it”
john: “No, wait… maybe we should get a feedback in our QA environment”
rick: “oh why? don’t we have already a green build?”
john: “well yes, but it doesn’t test everything”
rick: “oh OK… yes… it happens sometimes… let’s make this manual test… (after dozens and dozens of minutes). OK, it seems working. Now we can release it!”
john: “oh nooooo!”
rick: “what’s happened?”
john: “the step after the deploy in our QA env failed!”
rick: “and?”
john: “they are our ‘api-tests'”
rick: “what do they do? a sort of end to end tests?”
john: “no, we call “end to end test” tests that involve all services. These ‘api-tests’ are run just against this service”
rick: “oh ok, but why are we running them now and not with our build system?”
john: “because they are slow”
rick: “mhm… whatever… where can I find them?”
john: “they are in the same project. There is a specific directory for them”
rick: “so they are in the same project but we do not run them in our build system, right?”
john: “yes, because they are slow”
rick: “yeah I get it”
john: “anyway you can run them manually… you have just to run in IntelliJ xyz and then you can open that folder and run in IntelliJ xyz”
rick: “yeah… manually… of course… ok πŸ˜• let’s see why they are failing, right?”
john: “oh I found! the data they are based on are no more available… we have to find some others…”
rick: “sorry, are they based on data coming from other systems?”
john: “yes”
rick: “so if someone touches those systems and those data, our api-tests fail miserably, right?”
john: “yes”
rick: “and we need to check the error, find new data allowing them to pass and update them, right?”
john: “yes”
rick: “OK, it’s 6.00 PM… and I’m tired… can we fix this tomorrow?

Feelings, agreements, time

There are a lot of things happening in this conversation.
If you look at the feelings of rick and john, it seems clear that while both started with high energy and passion, rick‘s feelings are degenerating… but why? Even john‘s feeling are not so good when api-tests fail, but not for the rest of the conversation.
If you look at what they are discussing, it seems like rick was expecting something from the build system… but what is that?
If you look at the conversation itself, you can imagine that it required some time… but they were just finishing a feature, weren’t they?
What’s your opinion about this conversation?
Do you feel more near to rick or to john?

Rick is right

Rick is right.
How do I know that?
Because Rick is asking just one simple thing: reduce cognitive load needed in this project to understand that something can be delivered in production.

We all have our tools: make, ant, maven, gradle, npm, …
We all have our commands, “phases” or tasks.
But what is missing here is the most simple convention you need in your build system: when you run the default command of your build system and it is green, the software can be released in production.

Let’s imagine if you have dozens and dozens of projects: do you feel comfortable in reading dozens and dozens of docs (maybe the RELEASE chapter in your README.md) in order to understand how to make a release? do you think it’d be simple to follow dozens and dozens of checklists with different steps between each other on how to be sure your software is working as expected?

What about John?

I don’t know John.
But what I think is that John focused mainly on the software strictly related to the product forgetting that as an engineer/software-developer all processes and tools used during development phases of that software need the same care.
In this specific case, it seems the release process of that software have been left undone… as a checklist… maybe to be memorized and to teach to new colleagues…
Such a waste of time!

Excuses

“Yes, you’re right! But in my company we have XYZ so this cannot be done”

I won’t answer to one of my colleagues in this way, but because this is my blog, I can be totally direct (and probably a little bit rude):
This is just an excuse.
I know that you are an engineer, my dear reader.
And as an engineer, you know that there is “very often” a solution to everything (yeah “always” can be too much sometimes).

Focus on the outcome: how simple would be releasing your project with such a convention in place?

A (Debian) Linux TTY console that rocks!

No i3 or awesome here!
Just a fuck**** TTY console (oh well in a VBox :D)

It is a little bit tricky ’cause (I think) nowadays there’s no much people tweaking this aspect. I found a lot of posts suggesting how to do that using grub. The problem is: now we have grub 2 and it works in a different way.

So how have I obtained this tty?

First of all pay attention, ’cause I have done this on a Debian. I don’t know how it can be done in others Linux distributions, just because (as you can see later), I have used a Debian specific utility to configure the console font.
Anyway…

Configure grub 2

Open grub 2 configuration file:

  sudo vi /etc/default/grub

and set the following rows:

 GRUB_GFXMODE=800x600x32
 GRUB_GFXPAYLOAD_LINUX=keep

then run:

  sudo update-grub2

then reboot your system.

Change console font

Here I’ve used dpkg-reconfigure that is an utility provided by Debian.

So run:

  sudo dpkg-reconfigure console-setup

and then I selected:

  UTF-8
  . Combined - Latin etc... Greek
  Terminus
  6x12 (framebuffer only)

I think you have to reboot again… or maybe no… well if it doesn’t work immediately, try a reboot πŸ˜€

Why I wrote this post after so many years?
I’ll think about this in the next days and I’ll let you know in a couple of years πŸ˜€