Communication Through Code
Behind every product, there is a vision. People with various skills and experiences team up to achieve that vision.
Working with people is hard; the coordination of actions and missteps all depends upon the effectiveness of communication among people.
Communication may slow down or speed up the undertaking task. It is key to the success of any undertaking task.
This post is focused on programmers’ communication within a team and across teams.
Programming is a social activity. The first priority of a programmer to communicate with other programmers — Uncle Bob
We write code not to instruct computer only but to communicate with fellow programmers; it involves sharing of the code and ideas behind code.
Just like the way we speak, the way we write code becomes a deciding factor in the efficiency of communication.
There can be two types of interaction pattern:
Box Style — Someone is interested in using your code. The focus on code capability or functionality. Often this type of communication happens across teams.
Glass Style — Someone is looking at the innards of code for extending, inheriting, understanding or just like that. Often this type of communication happens within teams.
It is sensical to assume the quality of code defines the efficiency of communication.
How can we define the quality of a coding unit? Which characteristics are most important? Which characteristics affect communication?
The code can be associated with several characteristics:
Maintainability, Reusability, Extensibility, Simplicity, Implicitly, Performance, Testable, Bug Density, Conventions Compliance, Comments, and Documentation.
Characteristics affecting interaction
- Box styled: Documentation…
- Glass styled: Implicitly (expressiveness), Simplicity (conciseness)
Documentation is used to share knowledge. It is all about describing :
- Usage — Intent, Context, Responsibilities, API reference, Reference Manual.
- Internal details — The structure, models, process, states, control flows, workflows, test plans, deployment plan, capacity planning, contingency plan, configurations.
Documentation for Usage Mode
If clients can’t look inside the code (black-box), they entirely depend on the knowledge you shared. Documentation reduces guesswork and avoids tripping of questions.
Documentation may slow down the process of shipping deliverables. It is hard to maintain over time, but it is a necessity.
If you have to be right on documentation, then keep it small, meaningful and updated.
Documentation for Glass Mode interaction
Extensive comments clutter the code and obscure its understanding. Expressive code is adequate documentation. In any case, if it is not imparting any intent, it is useful to write a brief explanation.
Whenever we write code, it is resultant of some decisions. It is difficult to remember those decisions with time. Also, difficult for new joiner: people without the context of the judgment. It is good practice to keep small bits of decisions related information. ADR can be helpful in this context.
Simplicity = Conciseness of Code
Simplicity is all about keeping the code concise so that it is easy to manage and understand.
Simplicity leverages the language idioms or programming skills of function decomposition, formatting of the code.
Both sides of codes are computationally equivalent, but the right-sided one is better in understanding. It lacks unnecessary clutters.
Remember, tools are not perfect. No doubt they assist in avoiding some problems but enforcing robotic style-guide may not be suitable in some situations.
Do not sacrifice simplicity for the sake of a tool !
💭 Related Content
- Python is the choice for mathematician and physicists because you can do more with fewer lines; in other words, you can write short programs.
- Humans are bad at keeping short-term memory. It is effortful activity. It is helpful to keep the unit of code within view of the viewport.
When code cross boundaries of the viewport, then you have to scroll it up or down to have one view of the code in your mind.
Code to be understood = code in the view + code out of sight (cognitive load)
The key is to keep the unit of code short and manageable.
Implicity = Expressiveness of Code
Implicity is related to the understanding of code.
Reading code is more time consuming and painful than writing the code. People in the industry spend most of their time in the reading code. Implicity helps in reducing time in reading the code.
Implicity leverages programming skills of naming elements, comments, objects decomposition…
Both left, and right sides are computationally equivalent. However, it is easy to perceive the right-sided code. Just doing the naming right has drastically improved the code understandability and reduce the guesswork. Isn’t it?
Implicity helps in the long run of keeping it and helps to avoid problems like:
- It is possible that you come across your code after a long time and not able to understand it.
- Whenever a new member joins the team, there is a change in responsibilities distribution. Maybe she has to inherit the previously written code by building a sense of it by reading the code.
💭 Related Content
Code Obfuscators tools work by renaming, reformatting, optimizing the input code without affecting the functionality. These tools make resultant code looks ugly; making it hard and painful to be perceived by humans.
In other words, they make code to lose Implicity.
- ProGuard for Java
- BitBoost for Python
Both Simplicity and Implicity help in reducing the efforts of Maintenance.
There is no fixed script to follow. It is craftsmanship. Mastering the right skill requires a lot of reading, practice and most importantly: the desire.
One can be on the right track by developing the design thinking so-called Developer Empathy. It is walking in the shoes of your clients.
- Empathy in Development
- Naming it right
- Clean Code by Robert C Martin
- Understanding Software by Max Kanat-Alexander