Difference between revisions of "C programming/House of Technology C coding policy"

From Teknologisk videncenter
Jump to: navigation, search
m
m (→‎Commenting code)
 
(26 intermediate revisions by the same user not shown)
Line 13: Line 13:
 
*All function names should describe purpose and function.
 
*All function names should describe purpose and function.
 
*Use _ (underscore) as space.
 
*Use _ (underscore) as space.
−
*Use '''galaxy_soarsystem_planet''' approach instead of '''planet_solarsystem_galaxy'''
+
*Use '''galaxy_solarsystem_planet''' approach instead of '''planet_solarsystem_galaxy'''
 
{|
 
{|
 
|-
 
|-
Line 31: Line 31:
 
|-
 
|-
 
|}
 
|}
−
 
  
 
==Abbreviations==
 
==Abbreviations==
Line 73: Line 72:
 
</source>
 
</source>
 
=Documenting=
 
=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.
 +
 +
<source lang=c>
 +
/**********************************************************
 +
  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);
 +
        }
 +
</source>
 +
 
==Module headers==
 
==Module headers==
 
===.c files===
 
===.c files===
 +
Do not use version numbers i modules. Note date/auther and description of change in the modification log.
 
<source lang=c>
 
<source lang=c>
 
/**************************************************************************
 
/**************************************************************************
Line 93: Line 138:
 
Purpose.: The purpose of the module. (one or two lines)
 
Purpose.: The purpose of the module. (one or two lines)
 
***************************************************************************
 
***************************************************************************
−
Cavets..: Description of problems and future extensions
+
ToDo....: Description of problems and future extensions (TODO's)
 
***************************************************************************
 
***************************************************************************
 
Modification log:  
 
Modification log:  
Line 101: Line 146:
 
***************************************************************************/
 
***************************************************************************/
 
</source>
 
</source>
 +
 +
==Function headers==
 +
<source lang=c>
 +
/*************************** FUNCTION HEADER ******************************
 +
Name....: fx. timer0_init
 +
Author..: name
 +
***************************************************************************
 +
Abstract: Description
 +
Inputs..: Parameters
 +
Outputs.: Changes/return
 +
Status..: Local/Rrivate/Public...
 +
ToDo....: Wanted enhancements
 +
***************************************************************************
 +
Modification log:
 +
**************************************************************************/
 +
</source>
 +
 +
=Links=
 +
*[https://github.com/torvalds/linux/blob/master/Documentation/process/coding-style.rst Linus Torvalds Coding Style]
 +
 +
=References=
 +
<references/>
 
[[Category:C]]
 
[[Category:C]]

Latest revision as of 13:35, 1 July 2024

Kate.png 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

References

Retrieved from "http://mars.merhot.dk/w/index.php?title=C_programming/House_of_Technology_C_coding_policy&oldid=41322"