QC 3: Code Documentation

 “A thing of beauty is joy forever

Beauty lies in the eyes of beholder

One can enlist a lot more phrases about beauty, which brings a joy to the heart. The beauty of programming is that it’s a blend of science and art and is definitely a canvas on which the programmer paints their masterpiece. Or an abstract, which in other terms is called disaster.

Code Documentation is one of the most critical aspects of programming and also one of the most often neglected one. The value of code documentation is understood only over a period of time, much like red-wine. Documentation is not only about the textual part of the code i.e. code comments, but is also about the presentation, alignment, structure and most importantly, not cluttering the code. One critical aspect is that code documentation is NOT a substitute for missing out on the Design documents, but instead augments the Design documents. In the absence of a DD like in the case of some inherited code, Code documentation plays a vital role in providing the end-user/consumer a very valuable insight into the code.

There are different aspects of code documentation, some of which have been described below. However, for a seasoned programmer there are many more interesting and critical aspects of coding, which I plan to add in future. The list is definitely not exhaustive, but indicative and outlines what the author thinks are the first level critical aspects of code documentation.

1. Headers

Headers are the MOST important part of any code documentation. Whether it’s a file header or a function header, they contain a lot of critical information and should be maintained throughout the lifecycle of the project.

File Header typically consists of copyright along with organization specific information. If header files were tool-generated, then some text about the tool and flexibility to modify sources is also inserted i.e. whether the end-user can modify the contents of the file or not. In some organizations,  file headers also contain change-lists with descriptions about the changes introduced into the file and some have strings which are then read by a script and auto-header is inserted. Some examples are enlisted below.

Simple Organization Header

/* ABCD Organization Ltd Copyright 2000-2011 */

Tool Generated Header

// ABCD Organization Ltd Copyright 2000-2011
// Generated by the XYZ tool - DON'T MODIFY

Detailed Header

/* ******************************************* *
 * ABCD Organziation Ltd Copyright 2000 - 2011 *
 * Distributed under PQRS Licensing Terms      *
 * File Name: test.h                           *
 * File Location:/src/test/inc/test.h          *
 *                                             *
 * Changelist History                          *
 * =========================================== *
 * Change Id | Description                     *
 * =========================================== *
 * AA_0001    Added the support for feature A  *
 *            as part of macro FEAT_A which    *
 *            is compile-time enabled          *
 *                                             *
 * BB_0002    Removed the support for feature  *
 *            B and included place-holders     *
 * ******************************************* *
*/

Function headers are invaluable blocks of any good software code, which is often referred to by many documentation tools or experts during source code traversal. Popular documentation tools like Doxygen standardize the format of a function header which aids easier traversal and automatic document generation, which then can be referred by developers and customers alike.

Function headers typically contain information regarding the input and output parameters of the function, expected behavior/return type and brief description about the function being encapsulated. A sample function header is as below:

Function Header

/* ************************************************************************* *
 * Function Name: myFuncUnderDocumentation                                   *
 * Description:   This is a sample function header that can potentially be   *
 *                used by Doxygen Tool and generate an end-user document     *
 * Parameters:    param1 [in]: Parameter 1 which is an input parameter       *
 *                param2 [in]: Parameter 1 which is another input parameter  *
 *                param3 [out]: Output Parameter                             *
 * Return Type:   MY_SUCCESS on successful completion of the routine         *
 *                RETURN_FAILURE_01 on failure type 1                        *
 *                RETURN_FAILURE_02 on failure type 2                        *
 * ************************************************************************* *
*/

2. Macros

Macros are extensively used in programming either to enable/disable constructs or to contain a specific value. When used in nested IF conditions, it is imperative to ensure that the corresponding ENDIFs are properly documented. This helps to isolate the corresponding IFs and makes code reading a far easier and pleasant task. Consider the sample illustration below which outlines this aspect and the value-add provided by a good documented nested IF statements

#if MACRO_01

#if MACRO_02

#if MACRO_03

#endif //MACRO_03 ====> END OF MACRO_03

#if MACRO_04

#endif //MACRO_04 ====> END OF MACRO_04

#endif //MACRO_02 ====> END OF MACRO_02

#if MACRO_05

#endif //MACRO_05 ====> END OF MACRO_05

#endif //MACRO_01 ====> END OF MACRO_01

Another aspect would be appropriate naming of macros. Though this is addressed in coding guidelines (a post(s) in future), it is an integral part of code documentation which is often overlooked. In programming, one has a tendency to use native/raw numbers as is in any mathematical equation. Good programming practices mandate that source code shouldn’t contain these magic numbers and instead should be represented through macros. These macros should be named appropriately and shouldn’t be a plain name as MACRO_01. This is useless and doesn’t aid in making the process of understanding the source code any easier.

Consider the source below which is comparing the area of a circle.

if (current_value < (3.1415 * r * r))

The magic number 3.1415 should be replaced by a macro as shown below. However, if the macro is poorly named as SOME_MACRO_01, it doesn’t help the user to know that the equation is intended to signify the calculation of area of a circle.

if (current_value < (SOME_MACRO_01 * r * r))

Instead if the macro is named as PI_VALUE, it facilitates easier understanding of the sources and better code.

if (current_value < (PI_VALUE * r * r))

A flip side of macro naming would be very long names. Choosing a macro name is an art and should be designed considering the fact the coding guidelines mandate a maximum column number beyond which one can’t continue to code. If very long and exhaustive macro names are chosen, typical IF statements get spilled over multiple lines and code legibility reduces.

3. Source Code

Code documentation is one of the most widely debated and discussed subject in programming circles. Internet is full of good and not-so-good comments, with an entire section dedicated to the bloopers and funny comments. Jokes apart, code documentation is extremely essential for good software product development, which more often than not, gets neglected. The importance of code documentation is felt in maintenance phase of the project, when new additions or error fixes have to be introduced.

In today’s software development world, it is highly unlikely that a product code is developed out of scratch (except maybe standardization bodies or true R&D groups). More often than not, code is inherited. In this scenario, one truly feels the value of the code document by sheer presence or the lack of it. Without source code documentation, the effort of understanding the code and modifying the same just multiplies as a factor.

Source code documentation should be prudently chosen. Any extreme is usually unproductive. As described in earlier paragraphs, lack of source code documentation saps the available bandwidth out. In the same vein, too much of source code documentation is also a big NO-NO. One should NOT commit the sin of putting the DD in source code. In other words, the programmer shouldn’t use Source code documentation as an alternative or excuse for writing a good Design Document (DD). Source code documentation is like salt in cooking. When present in right amounts, it augments the taste. Lack of salt or excess salt makes the food non-edible and makes the same a big waste.

A sample illustration of good documented code is as below:

//Check if the current value is less than area of circle desired
if(current_value < (PI_VALUE * radius * radius))
{
   //Since the current value is less than area, return the current value
   return current_value;
}
else
{
     area = PI_VALUE * radius * radius;
     //As current value is more, invoke the scaler to map and reevaluate
     ret_val = myScaler(radius);

    // Check if scaled value is less than area and return the same
    // Else return area
    if(ret_val <= area)
         return ret_val;
    else
         return area;
}

Conclusion

Code documentation is a product of good programming practice that is inculcated over a period of time. It is the responsibility of senior members of the team to nurture and inculcate the habit of good code documentation from the time any developer enters the industry. Good code documentation goes a long way in creating some fantastic and truly world-class software products.

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