Introduction
Writing code is a complex task. It is not only about solving a problem through programming. It requires a great understanding of the software in development, the libraries and the development roadmap.
Once a project grows, older code becomes "unreadable" and "hard to understand".
To avoid this kind of issues, developers need to use architecture patterns, style guides, conventions, and more.
A good point to start improving the written code is following a style guide, for example, Google C++ Style Guide.
What is a style guide?
Programming style is a set of rules or guidelines used when writing the source code for a computer program. It is often claimed that following a particular programming style will help programmers to read and understand source code conforming to the style, and help to avoid introducing errors.
Taken from https://en.wikipedia.org/wiki/Programming_style.
There are many ways to define a style guide, but in short, it's a set of rules or guidelines which the code should follow. It doesn't tell how to write the code, but it does tell how it should look like and why.
Let's use an example, a typical loop on i:
for ( i = 0; i < 3; i++ )
std::cout << a[i] << std::endl;
Alright, all good there. Now, what if we share this code to one of our teammates?
Or even better questions: What do you think i is? What does a mean for you?
I, of course, know what they both mean. But I will forget it later too, if I don't read the full code.
Let's put the full code this time.
std::string a[] = {"Apple", "Banana", "Orange"};
int i;
for ( i = 0; i < 3; i++ )
std::cout << a[i] << std::endl;
So... Ohhh! a was an array of fruits! And we used i to loop through it! While the meaning of i is obvious, the meaning of a was unknown.
On this point you might wonder... "And what about the style guide?".
The variable name a is wrong according to Google C++ Style Guide, at least, in this context. Read the following:
General Naming Rules
Names should be descriptive; avoid abbreviation.
Give as descriptive a name as possible, within reason. Do not worry about saving horizontal space as it is far more important to make your code immediately understandable by a new reader. Do not use abbreviations that are ambiguous or unfamiliar to readers outside your project, and do not abbreviate by deleting letters within a word.
Taken from https://google.github.io/styleguide/cppguide.html#General_Naming_Rules.
So, it is definitely wrong to name as a our fruits.
Why? Well, I do own an app, which consists of more than 140 files, and around 8000-9000 lines of code. If you are going to navigate between 20 files to find out what a really means in it, you're free to do so, but I will not.
Source code can grow a lot. And tracking it around becomes expensive. For example, about the app I mentioned before, if I stopped developing it for 3 months, it could take me 8 days reading code to understand what everything means again so I can resume development.
For the app I just mentioned, I do follow the proper pattern architecture and style guide. Even so, when I stop developing it for 3 months, it takes me around 12 hours reading code to resume development.
Alright, then, continuing with our example, let's apply the General Naming Rules to our code:
std::string fruits[] = {"Apple", "Banana", "Orange"};
int i;
for ( i = 0; i < 3; i++ )
std::cout << fruits[i] << std::endl;
And... Wow! The code is now a bit easier to understand! Now, what if we exceed a bit and rename i too?
std::string fruits[] = {"Apple", "Banana", "Orange"};
int current_fruit;
for ( current_fruit = 0; current_fruit < 3; current_fruit++ )
std::cout << fruits[current_fruit] << std::endl;
Hmm, well, even if I don't mention that "current_fruit" is an index, it might be too clear only for us.
But if we crop away our definitions, someone might try the following:
if ( current_fruit == fruits[0] )
/* This should work, doesn't it? I mean, they are both fruits! */
It won't work, and for whoever tries it will be frustrating.
Let's rename properly our i. It's an index, and it's fruit-related, so, how about "fruit_index" instead?
std::string fruits[] = {"Apple", "Banana", "Orange"};
int fruit_index;
for ( fruit_index = 0; fruit_index < 3; fruit_index++ )
std::cout << fruits[fruit_index] << std::endl;
Oh! Now it makes sense! Even if we go past to the earlier comparison example, the error is clear at first sight!
if ( fruit_index == fruits[0] )
/* There is no way this will work! I mean, the right one is a fruit and the left one is an index! */
Do you see the error? Of course you should be able to see it!
Thus, if we go back to our first example but with our refactored code, like this:
for ( fruit_index = 0; fruit_index < 3; fruit_index++ )
std::cout << fruits[fruit_index] << std::endl;
Oh! It's now clear as daylight! Most people should be able to understand it fully now.
Even if we only see this:
if ( fruit_index == fruits[0] )
/* Do something */
We can clearly understand the error in the code! There is no need to check more code! Yay!
Google C++ Style Guide
Background
C++ is one of the main development languages used by many of Google's open-source projects. As every C++ programmer knows, the language has many powerful features, but this power brings with it complexity, which in turn can make code more bug-prone and harder to read and maintain.
The goal of this guide is to manage this complexity by describing in detail the dos and don'ts of writing C++ code. These rules exist to keep the code base manageable while still allowing coders to use C++ language features productively.
Taken from https://google.github.io/styleguide/cppguide.html#Background.
The Google C++ Style Guide is one of the most popular style guides for C++. Not only it explains how variables should be named, but also how source code should be organized, how to use namespaces properly, things to be careful when using classes, and far more than just that, while explaining why it should be done as specified.
It's compiled knowledge of hundreds if not thousands of skillful C++ developers, fairly summarized in a short guide in favor of open source projects.
It does not apply to all projects though, since some times the project will impose an style guide. For example, while using Microsoft Visual C++, following Microsoft's guidelines is proper, so please take this into consideration. Every programming language has it's own style guides, which, if well followed, can improve the source code quality greatly.
Feel free to check out the rest of the Google C++ Style Guide at the following link:
Google C++ Style Guide