Naming convention in C

Created by ThangVu.

Why do we need conventions?

• They help us understand our code more easily, we can learn quickly on a new project. When every people has the same convention, we do not waste much time to guess what they want to do?
• They reduce name proliferation. Without naming convention, we can have different name for the same thing. For example, when we want to name for the number of employees in a company, we can use num_employee, employee_num, no_of_employee, ... It could make confusion. 
• They help us compensate for programming language weaknesses. We can differentiate function, variable, global data, constant data... 

Routine name (function, macro) 

Some suggestions to have good routine name.

• Should be actions that describe everything the routine does, avoid meaningless verb. For example, names like handle_data(), perform_service() might not tell us sufficiently what the routine do. We should specific the action and object as much as possible. For instance, sort_and_print_data() is more informative than handle_data().
• Do not differentiate routine names solely by number. We should avoid using sort_and_print_data1(), sort_and_print_data2(). The numbers do not suggest anything about what the routine want to do. Instead, we should use sort_and_print_employee(), sort_and_print_equipment(). 
• Make routine name not too long and not too short. 
• Prefixes (is, get, set) are sometimes useful. We use is to ask a boolean question, get to get a value, set to set a value. Example: is_process_complete()

Variable name.

Variable name should describe fully the entity that the variable represents. Research shows that optimum variable name length is 10 to 16 characters. For example, if we want to name for the number of employee in Humax company, number_of_employees_in_humax_company is obviously too long. Meanwhile, employees or n_e_h are too short and do not describe fully the entity. A just right name is num_humax_employee.

In some cases, we prefer abbreviations for their convenience. However, other readers might not understand our abbreviations, we should comment exactly what they stand for? We should specify variable with unit (time, length), if needed.

Example:

#define  NUM_EMP   1000   /* Number of employees */
#define  BUF_LEN   1024   /* Length of buffer */
#define  PRO_DELAY  100   /* Propagation delay in miliseconds    */
#define  DIS_KM      30   /* Distance in KM */ 

Each variable name should represent only one entity, temporary variable is not an exception. Consider following example.

if(is_swap == 1){
     int temp = a;
     a = b; 
     b = c;
}
else if(is_solve_equation == 1)
{
     int temp = b^2 - 4*a*c;
     /* solve equation here */
}

This example use temp for two purposes, swapping and solving equation. It might confuse other readers and should be avoided by using different name for different purposes.

Comment your work

Almost programmer use not enough comment for there work, even no comment. Some claim that they write for themselves, but if we have a good comment routine, we will work in a group more easily.

First, comment should tell a story, write a brief comment at start of each source file to describe the main purpose of this file.

Second, comment on each function saying what function does, what types of arguments are, what possible values of arguments.

Here is an example of comment for a function.

/* Function name : sort_and_print_employee()
 * Argument 1    : epm_list list of employees
 * Purpose       : sort the employee names in order of Alphabet, and print employees' infomation
 * Return        : return 0 if success, return 1 if a problem occured
 * Modification  : By ThangVu, on 8/Aug/2016, check valid names before printing 
 */

int sort_and_print_employee(struct emp_info *emp_list){
     //do function here
}

General rules

Each project has its own convention, however, there are some general rule as follows:

• Name with leading and trailing underscores are reserved for system purposes and should be not use for user-created name.
• #define constants should be in all CAPS
• Enum constants should be in all CAPS
• Function, variable, struct, union should be in all lowercase, using underscore character as a separator. 
• Advoid names that look like other names. For example '1', 'l', 'I' look quite similar. If we use 'l' (for example, in loop counter), it will confused other reader, even ourselves if we read the code long time later. 

Good instruction about this topic: 

Steve McConnell, "Code complete", second edition
Recomended C Style and Coding standards
C Coding standard