CodeStandard
Coding Style
Coding Style
Table of Contents
Introdcution1 File Organization2 File Naming Conventions2 Program Files2 Header Files2 Comments4 Declarations5 Whitespace7 Operators9 Naming Conventions10 Constants11 Macros12 Examples13 mt_example.h13 mt_example.c14 Index a
1 Introdcution
This document describes a recommended coding standard for C programs.
1 Coding Style
1
2 File Organization
A file consists of various sections that should be separated by several blank lines. The length of file should be limited in 2000
lines and lines shouldn't more then 79 columns.
2 2.1 File Naming Conventions
The file name is consist of a module abbreviation (four or fewer characters), and an optional sub module abbreviation and the base name. The first character of the name should be a letter and all characters (except the period) should be lower-case letters and numbers. (e.g., db_dvbs_view.c)
2.2 Program Files
The suggested order of sections for a program file is as follows:
1. First in the file is a prologue that tells what is in that file.
2. Any header file includes should be next and the system include files like stdio.h should be included before user include
files.
3. Any defines and typedefs that apply to the file as a whole are next. One normal order is to have "constant'' macros first,
then "function'' macros, then typedefs and enums.
4. Next come the global (external) data declarations, usually in the order: externs, non-static globals, static globals.
5. The functions come last, and should be in some sort of meaningful order.
2.3 Header Files
1. It is common to put the following into each .h file to prevent accidental double-inclusion.
#ifndef __EXAMPLE_H__
#define __EXAMPLE_H__
... /* body of example.h file */
#endif /* __EXAMPLE_H__ */
2. Defining variables in a header file is not be allowed.
3. Header files should be functionally organized, i.e., declarations for separate subsystems should be in separate header
files.
4. Header files should not be nested, but it is acceptable to put all common #includes in one include file.
2
3 Comments
...
3
4 Declarations
1. The global variables is only used in the module. It is not allowed to use the global variables to deliver the data between a
module and others.
2. In general, globals should be grouped in a global structure.
3. Any variable whose initial value is important should be explicitly initialized.
int x = 1;
char *msg = "message";
struct boat winner[] =
{
{ 40, YAWL, 6000000L },
{ 28, MOTOR, 0L },
{ 0 },
};
4
4. When the actual values are unimportant, the enum facility is better.
enum bt { KETCH=1, YAWL, SLOOP, SQRIG, MOTOR };
struct boat {
int wllength; /* water line length in meters */
enum bt type; /* what kind of boat */
long sailarea; /* sail area in square mm */
};
5. The "pointer'' qualifier, *, should be with the variable name rather than with the type.
char *s;
6. The opening brace ({) should be on the separate line and the closing brace (}) should be same.
struct boat {
int wllength; /* water line length in meters */
int type; /* see below */
long sailarea; /* sail area in square mm */
};
/* defines for boat.type */
#define KETCH (1)
#define YAWL (2)
#define SLOOP (3)
#define SQRIG (4)
#define MOTOR (5)
7. Typedeffed names should have "_t" appended to their name.
typedef struct
{
int count;
char *name, *alias;
} splodge_t;
8. The return type of functions should always be declared.
9. The inner function of the module should be as a static function.
4
5 Whitespace
1. There should be 2 blank lines between the end of one function and the comments for the next.
2. A long string of conditional operators should be split onto separate lines.
if (NULL == foo->next
&& totalcount < needed
&& MAX_ALLOT => needed
&& server_active(current_input))
{
...
3. Keywords that are followed by expressions in parentheses should be separated from the left parenthesis by a blank. (The
sizeof operator is an exception.)
4. The null body of a for or while loop should be alone on a line and commented so that it is clear that the null body is
intentional and not missing code.
while (*dest++ = *src++)
; /* VOID */
5
5. Do not default the test for non-zero, i.e.
if (f() != FAIL)
is better than
if (f())
6. Goto statements is only used to break out into a separate function, with a success/failure return code.
for (...) {
while (...) {
...
if (disaster)
goto _ERROR_;
}
}
...
_ERROR_:
clean up the mess
7. The braces are always alone on a line.
control
{
statement;
statement;
}
i.e.
if (expr)
{
statement;
}
else
{
statement;
statement;
}
8. When a block of code has several labels (unless there are a lot of them), the labels are placed on separate lines.
switch (expr)
{
case ABC:
case DEF:
statement;
break;
case UVW:
statement;
/*FALLTHROUGH*/
case XYZ:
statement;
break;
}
5
6 Operators
Unary operators should not be separated from their single operand. Generally, all binary operators except '.' and '->' should be separated from their operands by blanks.
6
7 Naming Conventions
There are some general rules.
1. Function, typedef, and variable names, as well as struct, union, and enum tag names should be in lower case.
Variable:
Function:
2. Variable name with leading and trailing underscores is reserved for system purposes.
3. #define constants should be in all CAPS.
4. Enum constants are Capitalized or in all CAPS.
5. Macro "functions'' are in all CAPS.
6. Avoid names that differ only in case, like foo and Foo.
7
8 Constants
Numerical constants should not be coded directly. The #define feature of the C preprocessor should be used to give constants meaningful names.
8
9 Macros
Use an enclosing do-while to make the compiler insure that a macro is terminated with a semicolon.
#define SP3() \\\\
do { if (b) { int x; av = f (&x); bv += x; }} while (0)
9
10 Examples
10.1 mt_example.h
/*****************************************************************************/
/* Copyright (c) 2008 Montage Tech - All Rights Reserved */
/*****************************************************************************/
#ifndef __MT_EXAMPLE_H__
#define __MT_EXAMPLE_H__
#include
/*!
Description of mt_example.h
...
*/
/*! Description of MT_MACRO */
#define MT_MACRO 0
/*! Description of this enum */
typedef enum
{
/*! description of this MT_OK */
MT_OK = 0,
/*! description of this MT_FAIL */
MT_FAIL
} mt_ret_code_t;
/*!
Callback function type description
*/
typedef u8 (*mt_callback_fun_t)(u8 event, u32 param);
/*!
mt initialization
\return Return MT_FAIL if failed, MT_OK for succeed.
*/
mt_ret_code_t mt_init(void);
/*!
Description of mt_test
\param[in] param1 Description of param1
\param[in] param2 Description of param2
\param[in] p_param3 Description of p_param3
\param[in,out] p_param4 Description of p_param4
\param[out] p_param5 Description of p_param5
\return Return MT_FAIL if failed, MT_OK for succeed.
*/
mt_ret_code_t mt_test(u16 param1, u8 param2, u32 *p_param3, u8 *p_param4,
u8 *p_param5);
10 #endif /* __MT_EXAMPLE_H__ */
10.2 mt_example.c
/*****************************************************************************/
/* Copyright (c) 2008 Montage Tech - All Rights Reserved */
/*****************************************************************************/
/*!
Description of mt_example.c
...
*/
#include
#include
/*! Description of MT_NO_MAGIC_NUMBER_ALLOWED */
#define MT_NO_MAGIC_NUMBER_ALLOWED 10
/*!
Description of mt_struct_t
*/
typedef struct
{
/*! Description of p_x */
u8 *p_x;
/*! Description of y */
u8 y;
} mt_struct_t;
/*! Description of g_global_test */
u8 g_global_test = 0;
/*!
Description of test_fun
\return Description of return value
*/
static u8 test_fun(void);
/*!
Description of test_fun
\param[in] param1 Description of param1
\param[out] p_param2 Description of p_param2
\return Description of return value
*/
static u8 test_fun1(u8 param1, u32 *p_param2);
mt_ret_code mt_init(void)
{
return MT_OK;
}
mt_ret_code mt_test(u16 param1, u8 param2, u32 *p_param3, u8 *p_param4,
u8 *p_param5)
{
MT_ASSERT(0 != param1
10 && 0 != param2
&& NULL != p_param3
&& NULL != p_param4
&& NULL != p_param5);
u8 i = 0; // Description of i
u8 j = 0; // Description of j, maybe this description is so ...............
// long and exceed 80 lines.
u8 *p_test = NULL; // Description of p_test.
mt_struct_t struct_test[MT_NO_MAGIC_NUMBER_ALLOWED] =
{
(NULL, 0),
(NULL, 0),
(NULL, 1),
(NULL, 2)
}; // Description of struct_test
mt_struct_t struct_test1[MT_NO_MAGIC_NUMBER_ALLOWED];
memset(struct_test1, 0, MT_NO_MAGIC_NUMBER_ALLOWED * sizeof(mt_struct_t));
if (0 == i
&& 0 == j)
{
i++;
}
while (i < MT_NO_MAGIC_NUMBER_ALLOWED)
{
i++;
j++;
}
for (i = 0; i < MT_NO_MAGIC_NUMBER_ALLOWED; i++)
{
i++;
j++;
}
switch (j)
{
case MT_NO_MAGIC_NUMBER_ALLOWED:
{
i = 0;
}
break;
default:
;
}
return MT_FAIL;
}
static u8 test_fun(void)
{
return 0;
}
static u8 test_fun1(u8 param1, u32 *p_param2)
{
MT_ASSERT(0 != param1 && NULL != p_param2);
return 1;
}
10
11 Coding Style
Index
C
Comments 4
Constants 11
D
Declarations 5
E
Examples 13
F
File Naming Conventions 2
File Organization 2
H
Header Files 2
I
Introdcution 1
M
Macros 12
mt_example.c 14
mt_example.h 13
N
Naming Conventions 10
O
Operators 9
P
Program Files 2
W
Whitespace 7