C Code conventions
From S1MP3 Wiki
TODO : Apply the embedded C standard rules.
Contents |
C standard compliance
Our source code will respect the embedded ANSI C standard as much as possible.
Variable and Function Naming Convention
Standard Types
from stdint.h
int8_t int16_t int32_t int64_t uint8_t uint16_t uint32_t uint64_t
Basic Numeric types
Name Identifier Description -------- ----------- ----------------------------------------- uint8_t ub unsigned 8 bits uint16_t uw unsigned 16 bits uint32_t ud unsigned 32 bits uint64_t uq unsigned 64 bits int8_t b signed 8 bits int16_t w signed 16 bits int32_t d signed 32 bits int64_t q signed 64 bits void
Boolean logic
Name Identifier description -------- ----------- ----------------------------------------- bool bl boolean true/false
Character and String types
Name Identifier Description -------- ----------- ----------------------------------------- char c single character char* cp pointer to a single character char* sp pointer to a zero terminated string char[] ac array of characters char[] s zero terminated string
Floating Point types
Name Identifier Description -------- ----------- ----------------------------------------- float f floating point double ff double precision float
Miscellaneous types
Name Identifier Description -------- ----------- ----------------------------------------- FILE* fh file handle *(name) fp function pointer
Global variables
Global variables will be prefixed with "g".
Eg. gsText
Variable naming
Variable names will be short but informative.
The type prefix will be in lowercase.
Each word of the variable name will be capitalized.
Eg. sText fhIn ubDataIn
Procedure and Function naming
A procedure is defined as a function which returns void.
Functions will be named dynamically.
Type prefixes will be used only where there are conflicting defintions.
Eg. bGetVal ubGetVal wGetVal
Function grouping
Functions will be grouped by a Grouping Prefix followed by and underscore and then the name of the function.
Eg. kbd_GetKey dac_SetVol
Function Groups
Prefix Description -------- ----------------------------------------------------- dac digital analogue converter adc analogue digital converter scr screen kbd keyboard i2c i squared c interface ... see [[Swan API]] for the complete modules' list
Eg. dac_SetVol adc_SetQ scr_Plot kbd_PressKey i2c_bWrite i2c_wWrite
File Format
Character set
All text will be standard ASCII, using characters in the range 0x20 to 0x7F.
Line delimiting
Lines will be delimited with 0x0A aka LineFeed, LF, or "\n".
Whitespace
Tab stops will be at increments of TWO.
Tab characters (0x09 aka "\t") will NOT appear in text files, instead spaces will be used.
Trailing whitespace is NOT acceptable, due to limitiations imposed by "diff" and "cvs".
Column width
Where reasonable, column width will be limited to 78 characters.
Where this limit is impractacle, an absolute limit of 100 characters is imposed.
C Code
Comments
C and C++ commenting conventions are allowed.
/* a C comment */ // a C++ comment
Trailing comments will be C++.
Eg. for ( ; ; ) ; // loop forever
Section comments will be in the style:
Eg. // // Process the information //
Function header is:
Eg. ///*************************************************************************** /// group_[type]Function /// /// ...description... /// /// In: type name description /// ... ... ... /// type name description /// /// Out: type name description /// /// Notes: ... /// ///***************************************************************************
Code-line termination
If a conditional construct only utilises one line, then a space is placed before the terminating semi-colon.
Eg. for (cp=s; *cp; cp++) ; // Find end of string
OBS: the only time a code-line may terminate with a continuation marker "\"
is in #define statements.
All terminators on task lines will align.
eg.
#define x(y) \
do { \
task; \
another task; \
yeat another task; \
} while(0)
IF construction
simple one line expressions are valid.
Eg. if (expression) simple task ;
...note use of the " ;" line termination
Simple compound expressions need not be enclosed in braces.
Eg.
if (expression) simple task; else simple task;
If one task is complex, ALL conditions will be braced.
Eg.
if (expression)
{
complex task;
}
else
{
simple task;
}
? Operator
The ? operator is acceptable, although discretion is given to the code moderator as to whether any specific case may be considered abusive of obfuscative.
Switch
switches will be formatted thus:
switch (name)
{
case value1:
task;
// fall through to value2
case value2:
task;
break
default:
[task;]
break;
}
ALL switches will have a "default" case.
Return
Return values will be in braces.
Eg. return(0) return(cp) return(FALSE)
Value assignment
Any function call or operation where the result is stored will be clear by the spaces around the assignment operator.
Eg. x = y; x += fn(y);
Pre and Post increment and decrement
Legal
Eg. i++ i-- ++i --i
Where there is no functional difference, POST modification will be used.
Embedded evaluation
Is legal, but open to code moderation to protect the code from obfuscation.
assignments will be enclosed in parenthesis
if ( (fhIN = fopen("name","privs")) ==NULL )
return(dbg_SendMsg("open failed"), false);
Obfuscation
If the code-moderator deems the code to be deliberately obfuscated, then the code WILL be changed or rejected.
Rebuild
Every C and H file will include "rebuild.h" so that a full rebuild can be forced by touch'ing rebuild.h.
Human Language
All comments will be in English.
Comments in American are also valid.
File headers
EVERY C and H file will contain the following header:
/*============================================================================== * * _____ * / ___| * \ `--.__ ____ _ _ ___ * `--. \ \ /\ / / _` | '_ \ * /\__/ /\ V V / (_| | | | | * \____/ \_/\_/ \__,_|_| |_| * * * * All files in this archive are under the FreeBSD license. * * This software is distributed on an "AS IS" basis, * WITHOUT WARRANTY OF ANYKIND, either express or implied. * *============================================================================*/ /// /// $Id$ /// /// brief description: bla bla bla /// /// revision history /// /// When Who What /// ------------- ----- -------------------------------------------------------- /// 2005/oct/31 BOB Changed stuff /// /// ///=============================================================================
