Software Development is Complex Communication
Behind every piece of code produced by a human is an intention. The intention should answer the question: why should this code exist? Fundamentally, the quality of code is related to this intention. For example, saying that you have written an elegant piece of code without stating the intention of that code is non-sensical.
Software developers usually call this intention specification. All software should start from an informal specification, a representation of some intention that is shared by a group of people. I say should because sometimes, developers are too eager to start coding without a clue of what the intention really is. This can be because these informal specifications are not clear enough to be communicated or because the communication between team members is not effective.
Software development is the iterative process of breaking down an informal specification into roughly three layers of increasingly formal specifications:
- At the first layer, we have representations of thoughts and ideas: word clouds, pictures on a board, a couple of written paragraphs with a vision of the product.
- At the second layer, we have user stories, step-by-step stories that describe the interactions between the users and the software and how the intended problem is solved.
- At the third layer, we have executable specifications, aka programs, for each of the steps in the user stories. These programs are combined into larger programs and further refined until optimal levels of performance are achieved.
To reach decisions and go live with a product, you might need multiple iterations in each layer and be aware that your decisions impact the decisions of your neighbouring layers.
A common key element in this hierarchy is communication and it is fundamental for the success of a team to share a common vocabulary. It is through this common vocabulary that anyone can completely understand what someone wrote or said at a certain point in time. I believe the cognitive neuroscientist Stanislas Dehaene perfectly summarises in one sentence a fundamental problem in understanding:
Consciousness overflows language: we perceive vastly more than we can describe.
The process of faithfully describing a vision for a product takes a lot of energy and time. Still, you need it to achieve a high level of understanding within a team and ultimately it is through language that a team identity will be formed. It is extremely fulfilling to be part of a team where this happens because you feel that you have multiplied yourself by the number of team members. Understanding others leads to a high degree of confidence in your predictability powers — that makes you feel safe even if you are tackling problems totally outside your comfort zone.
Defining this common vocabulary for your team or company is a key task that will play an essential role in its culture. The philosopher Wittgenstein compared picking up words in a conversation to moving pieces in a chess game. If you are defining part of this common vocabulary, you need to anticipate the potential meanings these words have and how they might be perceived. Making these choices in a transparent and authentic way that brings the best of the team members is key to foster trust and avoid bullshit toxic environments.
From the perspective of a developer that works in the third layer, it’s important to understand how this common vocabulary spans natural languages and programming languages. A good developer is a good communicator and I like to break down this communication in three flavours:
- Communication upwards within your team. The typical way you communicate with a product manager/owner is through specifications at higher levels. Specification languages have emerged over the last decades with different levels of sophistication — one notable example being the Z notation language. These languages help you narrow down the implementation and leave less room for errors. Still, 99% of all specifications are written in vanilla natural languages. Sure, we can say that intentions are fuzzy by nature but ultimately it is just very expensive to generate and maintain formal specifications. It also doesn’t help to have a lot non-technical product managers combined with a fast and furious development environment. A dangerous flaw in this process is that developers do not really understand specifications and they can be understandably upset when the functional validation comes back to haunt them. Having a common vocabulary at this stage is crucial to obtain implementations that do not deviate too much from their intended specifications.
- Communication sideways with your future self. The period of time that you fully understand a piece of code is pretty short (in my experience, a couple of weeks) — and many developers have this distinct feeling of reading their code after several months without remembering typing any of it. In the end, it actually doesn’t even matter who wrote the code — you feel that you are reading the code written by someone else. The ways you apply this common vocabulary in your code (through documentation and/or code style conventions) will save a lot of time in the process of building the mental model of the code. Without a shared vocabulary, you feel lost, frustrated and your productivity drops.
- Communication downwards with the machine. When you are coming up with an executable specification, you are wrestling with a machine. A lot of non-technical people do not understand the toll these fights can take on a programmer. This is a potentially daunting process as a machine is not flexible and provides very little guidance. Coming up with tools or techniques that assist developers in this form of communication is in high-demand. Programming patterns and abstractions are part of our common vocabulary but are insufficient: we need more!
To become a good software developer it is important to understand these distinct forms of communication, the shared vocabulary in our team and to continuously improve it. This is a lot to ask but the reward of feeling part of an effective team will ultimately move you from thinking We are Great to feeling Life is Great.
