Convenții de cod - C

During the DSA lab and while solving homework, you will also get points for the way the source code is paged, tabbed, the naming of the functions and variables, and the general structure of the program. The conventions that need to be followed are:

• the segments of the file should appear in the following order:
  • header comment, describing the role of the file, author and the project it is part of;
  • import directives;
  • define directives;
  • data types (new structures or typedefs);
  • global variables (these you should avoid in most cases);
  • function prototypes;
  • function implementations; each implementation should have a short comment explaining the function role, the arguments and the return type;
  • footer comment, describing the changes in the file (this may be missing if the file is not under version control - svn, git, perforce, etc.);
• all segments of the file are split by a comment-line which appears also between functions;
• the main function, if it exists, is placed first;
• for if / do-while / for / case constructs and for method bodies, the open curly bracket is placed on the same line with the construct / function declaration and the closed curly bracket is placed on a separate line, on the same column with first letter from the construct/ declaration;
• an instruction block is indented by one extra tab in respect to the previous level;
• new data type names (as well as structures) start with an uppercase letter;
• function and variable names start with a lowercase letter;
• global variables start with a lowercase "g": (int g_my_global_var; or int gMyGlobalVar;)
• constant names are written in caps, words separated by the "_" character;
• the naming must be as explicit as possible regarding their purpose, in order to avoid excessive comments;
• it is allowed to insert a blank line, if a natural segregation of elements is obtained through it.

Notes:

• your code editor should be configured so that instead of a TAB character, it should insert 4 spaces;
• both camel case and underscore-separated words are accepted, as long as the notation is consistent throughout the program; so pick one and stick with it;
• always use brackets for "if" and "for" statements, even if there is only one statement in a block; the exception is for "if" when it has only one short statement in its block in which case both the if and the statement are placed on line: if(a > b) return a;

Example

/*******************************************************************
 *           Coding Conventions Style Example
 *          
 * Author: Radu Hobincu
 * Date: 09.03.2014
 * Description: This file contains functions and variables used
 *         to exemplify the use of coding styles and how the
 *         readability of a program improves when it is well 
 *         written.
 ******************************************************************/

#include<stdio.h>
#include<stdlib.h>

#define MAX_INT 0x7FFFFFFF
#define MAX(a, b) ((a) >= (b) ? (a) : (b))

/******************************************************************/
typedef unsigned short Age;
typedef char* String;

struct Person{
    String first_name;
    String last_name;
    Age age;
    String address;
    int weight;
};

/******************************************************************/
struct Person *g_myself;
struct Person *g_yo_momma;

/******************************************************************/
struct Person *create_person(String first_name, String last_name, 
        Age age, String address, int weight);
struct Person *find_yo_momma(struct Person **persons);
void delete_person(struct Person *person);

/******************************************************************
 * The main function of the program. 
 * @return the error code; 0 is execution is successful.
 */
int main(){
    g_myself = create_person("Radu", "Hobincu", 30, "Classified", 
        65);

    struct Person *persons[100];
    int i;
    for(i=0; i<100; i++){
        persons[i] = create_person("Some First Name", "Some Last Name", 
            i, "", rand());
    }

    g_your_mom = find_yo_momma(persons, 100);
    if(g_your_mom != NULL){
        printf("Here's yo momma! It's a global variable because there's "
            "not enough room on the stack!\n");
    }

    for(i=0; i<100; i++){
        delete_person(persons[i]);
    }

    delete_person(g_myself);
    return 0;
}

/******************************************************************
 * Allocates memory for a person and initializes each structure member. 
 * @param first_name the first name of the person
 * @param last_name the last name of the person
 * @param age the age of the person
 * @param address the address of the person
 * @param weight the weight of the person (if MAX_INT, then this is yo` momma!)
 * @return a pointer to the newly allocated and initialized person.
 */
struct Person *create_person(String first_name, String last_name, 
        Age age, String address, int weight){
    struct Person *person = (struct Person*)malloc(sizeof(struct Person));
    person->first_name = first_name;
    person->last_name = last_name;
    person->age = age;
    person->address = address;
    person->weight = weight;

    return person;
}

/******************************************************************
 * Finds yo` momma in an array of persons. 
 * @param persons the array of persons to look for yo` momma in
 * @param person_count the number of persons in the array (amazingly enough, yo`
 *         momma still counts as one).
 * @return a pointer to yo` momma or NULL if she couldn't be found.
 */
struct Person *find_yo_momma(struct Person **persons, unsigned person_count){
    int i;
    for(i=0; i<person_count; i++){
        if(persons[i]->weight == MAX_INT) return persons[i];
    }

    return NULL;
}

/******************************************************************
 * Deletes a person and frees any allocated resource.
 * @param person the person to delete (yo` momma might take a longer time...)
 */
void delete_person(struct Person *person){
    free person;
}

/******************************************************************
 * HISTORY:
 *
 * - 9.03.2014 - added first revision of the file;
 * - 9.03.2014 - added yo` momma and the size of the file quadrupled
 */