Difference between revisions of "C programming/House of Technology C coding policy"
From Teknologisk videncenter
m (→Commenting code) |
m (→Commenting code) |
||
| Line 73: | Line 73: | ||
=Documenting= | =Documenting= | ||
==Commenting code== | ==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. | 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 | *What - What is the purpose | ||
Latest revision as of 13:35, 1 July 2024
This article is under development....
Contents
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.
- Use int timer0_instance_counter instead of int timer0InstanceCounter
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:
**************************************************************************/