QC 4: Coding Guidelines

Coding Guidelines is a very touchy issue which is highly individualistic and organization specific. Every organization have their own standards and an apt of application of the same results in good quality code. Coding guidelines captures a lot of gamut, each of which can be debated at length as a separate post. However, imbibing some of the most common rules would require little effort, but go a long way in making source code, true masterpieces.

Before we look at the different coding guidelines, it is imperative to note that as with code documentation, sticking to guidelines is a habit which should be inculcated at a very young age. Habits die-hard and coding guidelines is definitely a habit which one should treasure for as long as they program. The true test of an individual is if the habit translates into guidelines being followed even when a very simple and straightforward piece of code needs to be written. If an individual can write a simple test code (like a Hello World program) adhering to the guidelines, one can be rest assured that they have arrived!!

Styles

Different companies have different styles of coding convention. Hungarian notation, Leszynski notation (variation of Hungarian), Upper Camel Case (a.k.a. Pascal Style) are some of the commonly used coding conventions. These conventions mandate the naming of variables, functions etc in a specific format. Few examples of naming a variable in Hungarian notation is as below

int              smallIntegerValue;
char             myLongNameArray[256];
struct           newStructObj;

Variable & Function Naming Conventions

Implementing a style improves the aesthetics part of the code. Augmenting the same with a little bit of extra additions like formalizing the naming convention for variables and functions enhance the code readability by leaps and bounds. Lot of organizations believe in adding the type of variable (either local or static or constant or global) into the name. Similarly, based on the function’s scope, the name of function is suitably designed to reflect the same.

Few examples of local variable naming convention is as shown below

int        lSomeLocalVariable; //Example of a local integer variable
static int sStaticCount;       //Example of a static integer
const int  cArrayOfConstants;  //Example of an array of constants
int        gGlobalVariable;    //Example of a global variable

Function naming also follows similar naming patterns as shown in the examples below

static void sSomeExampleFunction(); //Example of a static function
extern int  gGlobalScopeFunction(); //Example of a global function

From the aforementioned examples, it is apparent that the following simple rules improves the quality of software being developed immensely. However, this is just the guideline, but without following the next aspect of naming convention, it is useless

Design of Meaningful Names

Following the naming convention is one part of good programming practices. However, without proper names, it is rendered absolutely useless. When variables or functions are named, their name should reflect something about them. Generic names should be avoided at all costs as they don’t convey any useful information i.e. they are useless. Names should be designed in such a manner that they convey information about the variable like it’s scope, the necessity of the same or rather what does it represent.

Consider the following example where one needs to traverse a 2D array to calculate the sum of all elements of an array. More often than not, the following code is implemented.

for(i = 0; i < N; i++)
{
    for(j = 0; j < M; j++)
    {
         lSum += gArray[i][j];
    }
}

A simple interchange of i and j can have disastrous results from a performance perspective. Though one might be acclimatized to such coding practices, it is not a nice way of programming. An alternative implementation would be as below

for(lColCtr = 0; lColCtr < N; lColCtr++)
{
     for(lRowCtr = 0; lRowCtr < M; lRowCtr++)
     {
          lSum += gArray[lColCtr][lRowCtr];
     }
}

Just naming the variables in a more appropriate manner improves the readability and the overall quality of software code by leaps and bounds. This habit of naming the variables in a more appropriate manner should be inculcated from start as a good programming practice.

Tip: i, j and k have a very special place in programming history. More often than not, these are used as array iterators. It requires a lot of practice and hardwork to overcome them, but should be done so to become better programmers.

Alignment

Alignment though being an aesthetic part of programming is an extremely critical and value-adding feature of coding guidelines. Good aligned code is extremely easy to read and facilitates a logical separation of blocks. Alignment is again a matter of habit and practice and when perfected, can yield wonderful results.

To drive the point of alignment, consider the following non-aligned piece of code (without code documentation) too

int function(int **arr, int row, int height)
{
int i, j;
int sad=0;
for(i=0;i

If the same piece of code is aligned and documented properly, it will be a pleasure to read the masterpiece.

int function(int **pInputArr, int lRow, int lHeight)
{
    // Declare the variables
    int lRowCtr, lColCtr;
    int lSad = 0; // Initialize the SAD to Zero

    //Loop to calculate the SAD of the input arry
    for(lColCtr = 0; lColCtr < lHeight; lColCtr++)
    {
         for(lRowCtr = 0; lRowCtr < lRow; lRowCtr++)
         {
                lSad += pInputArr[lColCtr][lRowCtr];
         }
    }

    //Print out the generated SAD for debugging
    printf("[function] Generated Sad:%dn", lSad);

    // Return the SAD from the function
    return lSad;
}

Different organizations have a different policy regarding tabs. Some mandate a tab based aligned and some of them space based alignment. The definition of a tab in terms of number of spaces is also organization and OS specific. Typically, a tab is defined to be 4 spaces, but again is a policy implemented by a group.

Obfuscated Coding

Obfuscated Coding is a deliberate attempt at making machine code non-readable by humans. Obfuscate by definition means to darken or to confuse or to hide the intent. There is a specific need for the same at machine-code programming level. Interested programmers take part in the International Obfuscated C Coding Contest (IOCCC) competition.

However, some programmers implement straight forward modules in an obfuscated manner. This defeats the purpose of programming paradigm and creates more problems than any coding guideline aims to resolve. As a matter of general principle, one should always practice KISS principle i.e. Keep It Simple, Silly.  Unless one is working at machine-code programming level, any kind of obfuscated coding practices should be avoided.

Conclusion

Coding Guidelines can be enforced or imbibed. The former only forces programmers to practice the principles without any conviction. However, if the guidelines are imbibed and nurtured from a young age, programmers appreciate the value of good programming coding practices and software thus produced will typically be of superior quality. KISS principle is something that can be implemented at every programming step. Usually, the simplest form of code will be the most optimal and best code that can be generated. Or in others would typically be Quality Code.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s