xref: /nrf52832-nimble/rt-thread/documentation/coding_style_en.txt (revision 104654410c56c573564690304ae786df310c91fc)
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