Design patterns for team software development

Knowledge doesn’t spread automatically, but we can do something to help this process

Colorful Patterns by Tarra Kongsrude

Teamwork is a very good thing, but the coordination of a group of people sometimes leads to some problems.

The problem

With a large codebase, largely heterogeneous, we needed to share the knowledge about the code design.
In general it is difficult and boring to write technical documentation about how the application code is written. In fact, probably, this activity is a waste of time for the majority of developers.
In an ideal world, code should be clear, concise and self documented. In our reality, it isn’t.

We believe that code design is very important, especially for developers who don’t know the code base. The consciousness about how the code is written is fundamental because it leads to:

• a shorter time needed by the developer to edit the code with efficacy
• less bugs due to code misunderstanding and mistakes
• easier tests maintenance, because the developer has a better understanding of the code structure and on how he/she cloud test it

The solution

There are many ways to solve this problem, mainly related to documentation:

• in-code documentation: efficient, but only for new code. Old undocumented code is difficult to manage and to update. Last but not least, a lot of developers think that in-code documentation should not exist because the code must document itself.
• project technical documentation: inefficient without an automated tool, very expensive and difficult to maintain and update
• confluence wiki: good tool, but we are not so disciplined, so for us it’s practically impossible to maintain update docs
• meetings: probably the worst way to share knowledge about code design

Given the fact that unfortunately knowledge doesn’t spread automatically, we found a and elegant, fast and efficient solution.

So we decided to approach our problem from a new (at least for us!) point of view: software and architectural design patterns. What is a software design pattern?

A software design pattern is a general, reusable solution to a commonly occurring problem withing a given context

Our infrastructure is mainly based on microservices, so we have identified and created some design patterns that fitted well with our existing software. Some of them were very simple: for example we designed a pattern for queue consumers and another for queue producers.

The effectiveness of this approach was restricted only to a couple of simple rules:

• every developer must know all our design patterns (obviously!)
• every software/microservice must be designed and implemented using a design pattern previously defined

Following this simple rule, in a few months, we had our code base aligned with our pre-defined design patterns.
In this way, we don’t have to document our code because everyone that has the knowledge on our design patterns automatically know the structure of all our code. Basically, we have nothing to document.

Now we can focus on writing better documentation about the domain of our applications.