Saturday, October 16, 2021

Coding conventions

Preface

The video version of this article can be found on YouTube in English, Russian and Hebrew. The presentation is available here


Introduction

Let's start with the definition.

Coding conventions are a set of guidelines for a specific programming language that recommend programming style, practices, and methods for each aspect of a program written in that language. 

Why do we need conventions? It is believed that a programmer writes code for a computer that does not care whether the code is nice or ugly. However, 40-80% of time a programmer spends not on the development of the new code but on maintenance and refactoring of the old one. What is maintenance and refactoring? This is a process when a programmer (human) is reading existing code developed by himself or another programmer. The faster he does it, the quality of the product is higher, its complexity is lower and the team work is simpler.

Robert Martin, known as Uncle Bob that has written the famous book "Clean Code" said: "It doesn't require awful lot of skill to write a program that computer understands. The skill is writing a programs that human understand."

Objections

I have often heard various objections:
  • I am a professional with many years of experience
  • I have found my own conventions and tricks that make me more productive
  • Everyone can write code as he/she wants. 
  • I have always worked this way and will work this way.

The case is that coding conventions play a role of laws. Why does humankind need laws? We need laws to regulate relationship among  people. Robinson Crusoe could live without laws while he was alone on the island. So a programmer that is working alone could theoretically work without any conventions and be independent software vendor. However, any team member has to work according to the well known industrial standards. 

Conventions source

Where did conventions come from? There are different sources.

Sometimes decisions of well-known experts or traditions may become industrial standards. 

Often the source of convention is a crowd wisdom. If a lot of independent people have found the same way of usage of a digging stick as the most effective one, there is very low chance that somebody can improve this technique within reasonable time period.  The same can be relevant for the computer languages usage. 

Conventions and personal preferences

Sometimes personal preferences do not exactly match the well known conventions. Conventions are a set of rules that limit us when we are coding in specific language, so, if our personal rules are stronger than well known ones and do not directly contradict them, they can be used without any problem. 

Common practices are changing all the time. Commonly used conventions may become less popular or even wrong. Some conventions are based on reason that became irrelevant. We should stop using such conventions. 

There are general and language specific conventions. We should avoid adopting our habits that we got when coding in one language (environment, framework) to another. Respect the rules of the domain you are working in!

Conventions types

There are a lot of types of conventions. Let' take a brief look at some of them. 

Code formatting

The code formatting is the first thing we are thinking about when we discuss the coding conventions. 
Discussions between people that write the left curly braсe directly after the operator and those that prefer to move it to the beginning of the next line are as meaningless as the dispute between Lilliputs on which side to break the egg. The Lilliputs conflict caused the endless war that was terminated by Gulliver. The problem of the left curly brace fortunately does not lead to any war and can be resolved using the coding conventions for each language. 

Naming

Names are important. Our code is written according to the rules of the language using its reserved words and the names that we invent for our variables, functions, classes etc. More readable names make the code better.  

Best coding practices

There are best practices for each operator. Let's review one simple example.  We have for-loop with the code that should be executed only if some condition is true. Here the straight-forward version of the code:

for (int i = 0; i < n; i++) {
if (condition) {
// some code
}
}
However we can inverse the condition used in "if" statement, go to the next loop iteration and implement the code after the "if":
for (int i = 0; i < n; i++) {
if (!condition) {
continue;
}
// some code
}
Each approach has its advantages and disadvantages and the choice could be made using conventions. 


Conventions are dynamic


C language was born in 1970. In those days, screens were small and keyboards were inconvenient. Therefore, people tended to shorten names of functions and variables and they often used single-character names for variables. A lot of years passed and Java was invented. Java coding conventions suggest to use long, self-descriptive names. Many years passed since that moment and Scala language appeared. Scala combines Object Oriented and Functional paradigm. When we are coding using functional style the meaning of the variable is often obvious from the surrounding code and the names could be shorten without compromising the code readability. 

Thus, we returned to short names on the next phase of the languages evolution. 

Conventions and agile

During the last 10 or even more years agile methodologies have become more and more popular. 
Agile is the answer to the new challenge: we have to develop software according to ever-changing requirements. This cause us to refactor our code very frequently and deliver versions very fast. Once upon a time it was a common practice to deliver version every several months. These days we produce new version every week and sometimes several times a day. 

Nowadays programmers do not work for the same company for decades but move from one project to another relatively often. This means that many teams may have one or more new programmers that should be integrated into the team as quickly as possible. This is very difficult if code is not written according to the well known and widely used standards. 

Code ownership does not exist anymore. Each programmer can modify any part of the code written by himself or by any other team member. 

Many teams had practiced remote working and during last year of COVID more and more teams joined the club. 

Members of many teams that are developing the same product may live in different countries and time zones and may speak different languages. The communication in such teams is done mostly via code itself. The co-working is easier if the code is written according to the coding standards. 


Coding standards for different languages

Every language has its own coding standards. Here is the list of the most popular programming languages with links to documents that define coding guidelines for each language: 

Conclusions

We can significantly improve our software if we follow the coding standards.