Transmitter (source: hpgruesen)

The way software is being designed and built within an organization mirrors its culture and communication structures. This is better known as Conway’s Law, and while this notion may seem obvious on paper, if left unattended it can have a negative impact on a development team’s ability to drive efficiency and business value.

We’ve had the privilege to work with many clients from different business sectors. Each client has granted us the opportunity to see how their teams perceive the value of software within their organizations. We’ve also witnessed how the same types of systems (e.g. ERPs) in competing organizations raise completely different problems and challenges. As a result of these experiences, we’ve come to understand that the key to building high-quality software architecture is effective communication between every team member involved in the project who expects to gain value from a software system.

So, if you’re a software architect or developer and you want to improve your architectures or codebases, you’ll have to address the organizational parts as well. Research conducted by Graziotin et al1. states that software development is dominated by these often-neglected organizational elements, and that the key to high-quality software and productive developers is the happiness and satisfaction of those developers. In turn, the key to happy and productive developers is empowerment - both on an organizational and technical level.

Developers need to feel fulfilled when working. This means that their organization should enable them to train on improving their individual coding skills and to pay attention to software quality, so that they can continuously produce high quality products while being happy and satisfied. Not only that, but the development process - including team dynamics - should be optimized as well.

Defining a communication structure within your team

From a social or organizational perspective, one of the most important aspects of the development process are communication structures, specifically feedback loops. Effective feedback loops include a sender that encodes and sends a message, a receiver who receives, decodes and interprets that message and provides feedback to the sender. Having proper feedback loops in place makes the difference between clarity and confusion when it comes to software development.

We often see working feedback loops between developers and systems and amongst developers, but when others are added to the mix (i.e. architects, product managers, UX experience designers, and management), it becomes a different story. Clarity on goals, definitions of done and shared understanding of the technical choices get lost. One of the biggest pitfalls when it comes to feedback loops is ending up with one massive loop rather than multiple closed loops that can be measured. That is why it’s crucial to explicitly indicate who needs to communicate with whom and define multiple, separate feedback loops that can be measured.

Developing specific software quality standards

From a technical perspective, clarity and good communication are crucial. Just try to imagine a software development team that tries to self-organize and define their own non-functional requirements for the system they develop, such as maintainability, which is strongly related to the quality of the code produced. This team needs to define what quality is for them, the metrics to monitor, as well as the standards to use. Most often, such a team fails or encounters major roadblocks to implementing these standards. In a survey the Software Improvement Group (SIG) conducted around code quality habits, the most common reason for failing to use any quality standards is the “lack of consensus on what software quality is and which standards to use.”

We would like to think differently here and claim that maintainability of source code can be measured and standardized. Our principle is that maintainability requires following simple guidelines that are not sophisticated at all. The following guidelines guarantee sufficient maintainability:

  • Write short and simple units of code: A developer should try to limit the length of code units to 15 lines of code. This can be done by not writing units that are longer than this metric, or by splitting long units into multiple smaller units until each unit has at most 15 lines of code. Small units are easy to understand, easy to test, and easy to reuse.
  • Write code once: This can be achieved by avoiding copying code and writing reusable, generic code and/or calling existing methods. This improves maintainability because when code is copied, bugs need to be fixed at multiple places, which is inefficient and error-prone.
  • Separate concerns in modules: A developer should avoid large modules in order to achieve loose coupling between them. This can be avoided by assigning responsibilities to separate modules and hiding implementation details behind interfaces. Changes in a loosely coupled codebase are much easier to oversee and execute than changes in a tightly coupled codebase.
  • Couple architecture components loosely: This can be done by minimizing the relative amount of code within modules that is exposed to (i.e., can receive calls from) modules in other components. Maintainability is improving by doing that as independent components facilitate isolated maintenance.

You can see why it’s not that easy to maintain architectural quality in software teams. It requires effective communication with clear feedback loops and clearly defined quality standards. Getting there—and optimizing for business value—means taking the time to reflect on both your organizational and development structures.

1 Daniel Graziotin, Fabian Fagerholm, Xiaofeng Wang, and Pekka Abrahamson 2017. On the Unhappiness of Software Developers. In Proceedings of 21st International Conference on Evaluation and Assessment in Software Engineering, Karlskrona, Sweden, June 15–16 2017 (EASE ’17)

This post is a collaboration between O'Reilly and SIG. See our statement of editorial independence.

Article image: Transmitter (source: hpgruesen).