Communication Through Code

Programmers’ language.

Puneet Sapra
Dec 2, 2017 · 5 min read

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.

The code becomes central to communication.

Just like the way we speak, the way we write code becomes a deciding factor in the efficiency of communication.

Interaction Pattern

There can be two types of interaction pattern:

Box Mode | Glass Mode
Box Mode | Glass Mode

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.

Communication Quality

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

Documentation is used to share knowledge. It is all about describing :

  1. Usage — Intent, Context, Responsibilities, API reference, Reference Manual.
  2. 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.

Code Example is from Oracle Tutorials

Tools like Checkstyle (Java), linting (CSS, Javascript, Sass, Python) may enforce some useless rules which may disturb the beauty of code.

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.
  • The usage of lambda (in Python, Java, JavaScript, C#) makes function code clean and more expressive subjectively.
  • 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.

  • Uglify for JavaScript
  • 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.


The Mighty Programmer

Software Design and Architecture Series | More at…

Puneet Sapra

Written by

Software Design Enthusiast. https://themightyprogrammer.dev/ https://www.linkedin.com/in/saprapuneet/

The Mighty Programmer

Software Design and Architecture Series | More at https://themightyprogrammer.dev

More From Medium

More on Software Development from The Mighty Programmer

More on Software Development from The Mighty Programmer

Uploading files over the web

More on Software Development from The Mighty Programmer

More on Software Development from The Mighty Programmer

Custom Event with RxJS

More on Software Engineering from The Mighty Programmer

More on Software Engineering from The Mighty Programmer

Level 0 — Coding Standard with EditorConfig

Welcome to a place where words matter. On Medium, smart voices and original ideas take center stage - with no ads in sight. Watch
Follow all the topics you care about, and we’ll deliver the best stories for you to your homepage and inbox. Explore
Get unlimited access to the best stories on Medium — and support writers while you’re at it. Just $5/month. Upgrade