1 RT-Thread Coding Style 2 3This is an developing instruction for RT-Thread developers. As an open source 4software, RT-Thread is done by the cooperation of different people. This 5document is a guide for RT-Thread developers and please obey it if you are. 6RT-Thread users could also get to know some conventions in the code through it 7and thus easier to understand the implementations of RT-Thread. 8 9 101. Directory Naming 11 12In normal conditions, please name directories in lower-case. Directories should 13have descriptive names. For example, the port of a chip should be composed of 14the name of the chip and the category of the chip. Directories under components/ 15should stand for what the component does. 16 17 182. File Naming 19 20In normal conditions, please name files in lower-case. If the file is 21referencing other places, it can have the original name. To avoid naming 22collision, do not use general names or the names that are frequently used. 23 24 253. Header Files 26 27To avoid include the same header file for multiple times, you need to define a 28symbol like this: 29 30 #ifndef __FILE_H__ 31 #define __FILE_H__ 32 /* header file content */ 33 #endif 34 35The symbol should begin and end with "__" to avoid naming collision. The words 36of the file name should be connected by "_". 37 38 394. Header File Comments 40 41In every header file, there should be copyright information and Change Log 42record like this: 43 44 /* 45 * File : rtthread.h 46 * This file is part of RT-Thread RTOS 47 * COPYRIGHT (C) 2006, RT-Thread Development Team 48 * 49 * The license and distribution terms for this file may be 50 * found in the file LICENSE in this distribution or at 51 * http://www.rt-thread.org/license/LICENSE. 52 * 53 * Change Logs: 54 * Date Author Notes 55 * 2006-03-18 Bernard the first version 56 * 2006-04-26 Bernard add semaphore APIs 57 * ... 58 */ 59 60 615. Structure Defines 62 63Please name structures in lower-case and connect words with "_". For example: 64 65 struct rt_list_node 66 { 67 struct rt_list_node *next; 68 struct rt_list_node *prev; 69 }; 70 71Braces should have their own lines and the members should be defines with 72indent. 73 74The names of type defines such like structure types should be the structure name 75plus "_t". For example: 76 77 typedef struct rt_list_node rt_list_t; 78 79 80In order to be easily referenced, the types of objects in kernel is pointer. For 81example: 82 83 typedef struct rt_timer* rt_timer_t; 84 85 866. Macros 87 88In RT-Thread, please use upper-case names for macro definitions. Words are 89connected by "_". Like: 90 91 #define RT_TRUE 1 92 93 947. Function Naming and Declaration 95 96Please name functions in lower-case and separate words with "_". API provided to 97upper application should be declared in header files. If the function don't have 98parameters, it should be declared as void: 99 100 rt_thread_t rt_thread_self(void); 101 102 1038. Commenting 104 105Please use English to comment. There shouldn't be too much comments and the 106comments should describe what does the code do. And it should describe how the 107complicated algorithm works. Comments to statements should be placed before them 108or right of them. Anther places are illegal. 109 110 1119. Indent 112 113Please use TAB or 4 spaces to indent. It's preferred to use 4 spaces. If no 114other special meanings, the indent should begin right after "{": 115 116 if (condition) 117 { 118 /* others */ 119 } 120 121The only one exception is switch. In switch-case statements, "case" should be 122aligned with "switch": 123 124 switch (value) 125 { 126 case value1: 127 break; 128 } 129 130"case" is aligned with "switch", the following code block should be indented. 131 132 13310. Braces and Spaces 134 135For ease of reading, it is advised that braces should occupy the whole line 136instead of following other statements. Like: 137 138 if (condition) 139 { 140 /* others */ 141 } 142 143When matching braces have their own lines, the reader would identify the code 144blocks easily. 145 146There should be a space before parentheses when it's not a function call. For 147example: 148 149 if (x <= y) 150 { 151 /* others */ 152 } 153 154 for (index = 0; index < MAX_NUMBER; index ++) 155 { 156 /* others */ 157 } 158 159In expressions, there should be a space between most binary and ternary 160operators and the strings. No spaces around(inside) parentheses, like: 161 162 if ( x <= y ) 163 { 164 /* other */ 165 } 166 167This is a bad practice. 168 169 17011. trace, log Informations 171 172In RT-Thread, rt_kprintf is a commonly used logging routine. In RT-Thread 173rt_kprintf is implemented as a polling, non-interrupting string output. It is 174suitable in "instant" situations such as interrupt context. The polling method 175would have influence to the timing sequence of the log output. 176 177It is not recommended to use rt_kprintf frequently. Unless you are aware of that 178it's not a big deal to run slower. 179 180Logging should be off by default and can be turned on by a switch(e.g. a 181variable or a macro). When logging, it should be easy to understand and easy to 182determine where the problem is. 183 184 18512. Functions 186 187Functions in kernel should be K.I.S.S. If the function is too long, you should 188split it into smaller ones and make each of them simplified and easy to 189understand. 190 191 19213. Objects 193 194The kernel of RT-Thread uses object-oriented tech in C. The naming convention 195is: structure names are the object names, object names + verb phrases are the 196method names of objects: 197 198 struct rt_timer 199 { 200 struct rt_object parent; 201 /* other fields */ 202 }; 203 typedef struct rt_timer* rt_timer_t; 204 205The definition of structure rt_timer stands for the object definition of timer 206object. 207 208 rt_timer_t rt_timer_create(const char* name, 209 void (*timeout)(void* parameter), void* parameter, 210 rt_tick_t time, rt_uint8_t flag); 211 rt_err_t rt_timer_delete(rt_timer_t timer); 212 rt_err_t rt_timer_start(rt_timer_t timer); 213 rt_err_t rt_timer_stop(rt_timer_t timer); 214 215rt_timer + verb phrase stands for the method that could be used on timer object. 216 217When creating a new object, think twice on memory allocations: whether a static 218object could be created or it could only created dynamically on heap. 219 22014. Use astyle to format the code automatically 221parameters: --style=allman 222 --indent=spaces=4 223 --indent-preproc-block 224 --pad-oper 225 --pad-header 226 --unpad-paren 227 --suffix=none 228 --align-pointer=name 229 --lineend=linux 230 --convert-tabs 231 --verbose 232 233