documentation/coding_style_en.txt: added

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

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.