C programming/House of Technology C coding policy

This article is under development....

Naming

Variable names

• All variable names should be in lower case.
• All variable names should describe purpose and content.
• Use _ (underscore) as space.
  • Use int timer0_instance_counter instead of int timer0InstanceCounter
    • If you abbreviate and use tim0_inst_cnt remember to list the abbreviations in the Abbreviation Table.

Function names

• All function names should be in lower case.
• All function names should describe purpose and function.
• Use _ (underscore) as space.
• Use galaxy_solarsystem_planet approach instead of planet_solarsystem_galaxy

best approach	dont use
timer0_start()	start_timer0()
timer0_stop()	stop_timer0()
timer0_init()	init_timer0()
timer1_start()	start_timer1()
timer1_stop()	stop_timer1()
timer1_init()	init_timer1()

Abbreviations

If abbreviations are used - use logical abbreviations and make a abbreviation table

/*Abbreviation Table
disp       == display
dsp        == digital signal processor
tim        == timer
inst       == instance
cnt        == counter

...
*/

Programming style

Indents

Use K&R or Allman indents. But do it consistently.

K&R example

if (x == y) {
    x++;
    foo();
} else {
    x--;
    bar();
}

Allman

if (x == y) 
{
    x++;
    foo();
} 
else 
{
    x--;
    bar();
}

Documenting

Commenting code

 “Code tells you how; Comments tell you why.”
   — Jeff Atwood (aka Coding Horror)

Write what the purpose of the code is - not what the code do. A fellow programmer knows how the programming language works - but not the purpose and function of your code.

• What - What is the purpose
• Why - Why is it necessary
• How - How does it do it

Example

The example below is a codesnip of a brute force decryption attack program, which searches all keys until it find a partial known/guessed cleartext message - known as a crib in the crypted message known as the ciphertext.

Note

the comments explains the purpose of the code - not how the code works. A peer progammer should know how the code works and need to know what the purpose of the code is.

/**********************************************************
   Abbreviation/explanation table
   ==============================

   cipher       = Crypt/decrypt algorithm
   ciphertext   = The crypted message
   cleartext    = The unencrypted message
   crib         = A known/hacked/guessed part of cleartext
**********************************************************/


        /* Allocate memory to store the ciphertext  */
        ciphertext = (int *) malloc(ciphertext_size * sizeof(int));
        if ( ciphertext == NULL ) {
                err(2,"Can't allocate memory for ciphertext message.");
                exit(2);
        }
        /* Read the Ciphertext into memory */
        for (i=0; i < ciphertext_size; i++) {
                if ((cipher[i] = fgetc(fpin)) == EOF) {
                        err(3,"Can't read from ciphertext file. (Perhaps it's shorter than the Crib)");
                        exit(3);
                }
        }
        /* Allocate memory to store the crib */
        crib = (int *) malloc(crib_size*sizeof(int));
        if ( crib == NULL ) {
                err(4,"Can't allocate memory for crib message.");
                exit(4);
        }

Module headers

.c files

Do not use version numbers i modules. Note date/auther and description of change in the modification log.

/**************************************************************************
  #     #
  ##   ##  ######  #####    ####     ##    #    #   #####  ######   ####
  # # # #  #       #    #  #    #   #  #   ##   #     #    #       #    #
  #  #  #  #####   #    #  #       #    #  # #  #     #    #####   #
  #     #  #       #####   #       ######  #  # #     #    #       #
  #     #  #       #   #   #    #  #    #  #   ##     #    #       #    #
  #     #  ######  #    #   ####   #    #  #    #     #    ######   ####
 
***************************************************************************
Author..: name <mail@address>
Company.: House of Technology at Mercantec ( http://www.mercantec.dk )
date....: 2012 Nov. 13
***************************************************************************
Abstract: Brief description (two to ten lines)
Purpose.: The purpose of the module. (one or two lines)
***************************************************************************
ToDo....: Description of problems and future extensions (TODO's)
***************************************************************************
Modification log: 
***************************************************************************
License:  Free open software but WITHOUT ANY WARRANTY.
Terms..:  see http://www.gnu.org/licenses
***************************************************************************/

Function headers

/*************************** FUNCTION HEADER ******************************
Name....: fx. timer0_init
Author..: name
***************************************************************************
Abstract: Description
Inputs..: Parameters 
Outputs.: Changes/return
Status..: Local/Rrivate/Public...
ToDo....: Wanted enhancements
***************************************************************************
Modification log:
**************************************************************************/

Links

• Linus Torvalds Coding Style