documentation/coding_style_en.txt: added

git-svn-id: https://rt-thread.googlecode.com/svn/trunk@1828 bbd45198-f89e-11dd-88c7-29a3b14d5316

1 files changed, 218 insertions, 0 deletions

diff --git a/documentation/coding_style_en.txt b/documentation/coding_style_en.txt
new file mode 100644
index 0000000000..c66d35a6cf
--- /dev/null
+++ b/documentation/coding_style_en.txt
@@ -0,0 +1,218 @@
+                           RT-Thread Coding Style

+

+This is an developing instruction for RT-Thread developers. As an open source

+software, RT-Thread is done by the cooperation of different people. This

+document is a guide for RT-Thread developers and please obey it if you are.

+RT-Thread users could also get to know some conventions in the code through it

+and thus easier to understand the implementations of RT-Thread.

+

+

+1. Directory Naming

+

+In normal conditions, please name directories in lower-case. Directories should

+have descriptive names. For example, the port of a chip should be composed of

+the name of the chip and the category of the chip. Directories under components/

+should stand for what the component does.

+

+

+2. File Naming

+

+In normal conditions, please name files in lower-case. If the file is

+referencing other places, it can have the original name. To avoid naming

+collision, do not use general names or the names that are frequently used.

+

+

+3. Header Files

+

+To avoid include the same header file for multiple times, you need to define a

+symbol like this:

+

+	#ifndef __FILE_H__

+	#define __FILE_H__

+	/* header file content */

+	#endif

+

+The symbol should begin and end with "__" to avoid naming collision. The words

+of the file name should be connected by "_".

+

+

+4. Header File Comments

+

+In every header file, there should be copyright information and Change Log

+record like this:

+

+	/*

+	 * File      : rtthread.h

+	 * This file is part of RT-Thread RTOS

+	 * COPYRIGHT (C) 2006, RT-Thread Development Team

+	 *

+	 * The license and distribution terms for this file may be

+	 * found in the file LICENSE in this distribution or at

+	 * http://www.rt-thread.org/license/LICENSE.

+	 *

+	 * Change Logs:

+	 * Date           Author       Notes

+	 * 2006-03-18     Bernard      the first version

+	 * 2006-04-26     Bernard      add semaphore APIs

+	 * …

+	*/

+

+

+5. Structure Defines

+

+Please name structures in lower-case and connect words with "_". For example:

+

+	struct rt_list_node

+	{

+		struct rt_list_node	*next;

+		struct rt_list_node	*prev;

+	};

+

+Braces should have their own lines and the members should be defines with

+indent.

+

+The names of type defines such like structure types should be the structure name

+plus "_t". For example:

+

+	typedef struct rt_list_node rt_list_t;

+

+

+In order to be easily referenced, the types of objects in kernel is pointer. For

+example:

+

+	typedef struct rt_timer* rt_timer_t;

+

+

+6. Micros

+

+In RT-Thread, please use upper-case names for micro definitions. Words are

+connected by "_". Like:

+

+	#define RT_TRUE 						1

+

+

+7. Function Naming and Declaration

+

+Please name functions in lower-case and separate words with "_". API provided to

+upper application should be declared in header files. If the function don't have

+parameters, it should be declared as void:

+

+	rt_thread_t rt_thread_self(void);

+

+

+8. Commenting

+

+Please use English to comment. There shouldn't be too much comments and the

+comments should describe what does the code do. And it should describe how the

+complicated algorithm works. Comments to statements should be placed before them

+or right of them. Anther places are illegal.

+

+

+9. Indent

+

+Please use TAB or 4 spaces to indent. It's preferred to use 4 spaces. If no

+other special meanings, the indent should begin right after "{":

+

+	if (condition) 

+	{

+		/* others */

+	}

+

+The only one exception is switch. In switch-case statements, "case" should be

+aligned with "switch":

+

+	switch (value)

+	{

+	case value1:

+		break;

+	}

+

+"case" is aligned with "switch", the following code block should be indented.

+

+

+10. Braces and Spaces

+

+For ease of reading, it is advised that braces should occupy the whole line

+instead of following other statements. Like:

+

+	if (condition)

+	{

+		/* others */

+	}

+

+When matching braces have their own lines, the reader would identify the code

+blocks easily.

+

+There should be a space before parentheses when it's not a function call. For

+example:

+

+	if (x <= y)

+	{

+		/* others */

+	}

+

+	for (index = 0; index < MAX_NUMBER; index ++)

+	{

+		/* others */

+	}

+

+In expressions, there should be a space between most binary and ternary

+operators and the strings. No spaces around(inside) parentheses, like:

+

+	if ( x <= y )

+	{

+		/* other */

+	}

+

+This is a bad practice.

+

+

+11. trace, log Informations

+

+In RT-Thread, rt_kprintf is a commonly used logging routine. In RT-Thread

+rt_kprintf is implemented as a polling, non-interrupting string output. It is

+suitable in "instant" situations such as interrupt context. The polling method

+would have influence to the timing sequence of the log output.

+

+It is not recommended to use rt_kprintf frequently. Unless you are aware of that

+it's not a big deal to run slower.

+

+Logging should be off by default and can be turned on by a switch(e.g. a

+variable or a micro). When logging, it should be easy to understand and easy to

+determine where the problem is.

+

+

+12. Functions

+

+Functions in kernel should be K.I.S.S. If the function is too long, you should

+split it into smaller ones and make each of them simplified and easy to

+understand.

+

+

+13. Objects

+

+The kernel of RT-Thread uses object-oriented tech in C. The naming convention

+is: structure names are the object names, object names + verb phrases are the

+method names of objects:

+

+	struct rt_timer

+	{

+		struct rt_object parent;

+		/* other fields */

+	};

+	typedef struct rt_timer* rt_timer_t;

+

+The definition of structure rt_timer stands for the object definition of timer

+object.

+

+	rt_timer_t rt_timer_create(const char* name,

+		void (*timeout)(void* parameter), void* parameter,

+		rt_tick_t time, rt_uint8_t flag);

+	rt_err_t rt_timer_delete(rt_timer_t timer);

+	rt_err_t rt_timer_start(rt_timer_t timer);

+	rt_err_t rt_timer_stop(rt_timer_t timer);

+

+rt_timer + verb phrase stands for the method that could be used on timer object.

+

+When creating a new object, think twice on memory allocations: whether a static

+object could be created or it could only created dynamically on heap.