1@page page_rtt_code_style_en RT-Thread Coding Style
2
3This is an developing instruction for RT-Thread developers. As open source
4software, RT-Thread is created by the cooperation of different people. This
5document is a guide for RT-Thread developers. Please obey it as you develop.
6RT-Thread users should also get to know some conventions in the code through it
7and thus easier to understand the implementations of RT-Thread.
8
9
10# 1. Directory Naming
11
12In normal conditions, please name directories in lowercase. 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 name what the component does.
16
17
18# 2. File Naming
19
20In normal conditions, please name files in lowercase. 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
25# 3. 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 "_". (This convention is called "snake case".)
37
38
39# 4. Header File Comments
40
41In every header file, there should be copyright information and Change Log
42record like this:
43
44    /*
45    * Copyright (c) 2006-2020, RT-Thread Development Team
46    *
47    * SPDX-License-Identifier: Apache-2.0
48    *
49    * Change Logs:
50    * Date           Author       Notes
51    * 2006-03-18     Bernard      the first version
52    * 2006-04-26     Bernard      add semaphore APIs
53    */
54
55# 5. Structure Defines
56
57Please name structures in lowercase and connect words with "_". For example:
58
59    struct rt_list_node
60    {
61        struct rt_list_node *next;
62        struct rt_list_node *prev;
63    };
64
65Braces should have their own lines and the members should be indented.
66
67The names of type defines such as structure types should be the structure name
68plus "_t". For example:
69
70    typedef struct rt_list_node rt_list_t;
71
72
73In order to be easily referenced, the types of objects in the kernel are pointers. For
74example:
75
76    typedef struct rt_timer* rt_timer_t;
77
78
79# 6. Macros
80
81In RT-Thread, please use uppercase names for macro definitions. Words are
82connected by "_". Like:
83
84    #define RT_TRUE                         1
85
86
87# 7. Function Naming and Declaration
88
89Please name functions in lowercase. Separate words with "_". The API provided to
90upper application should be declared in header files. If the function don't have
91parameters, it should be declared as void:
92
93    rt_thread_t rt_thread_self(void);
94
95
96# 8. Commenting
97
98Please use English to comment. There shouldn't be many comments as the
99comments should describe what the code does. It should describe complicated
100algorithms, for example. Comments for statements should be placed before the
101statements or to the right of them. Any other locations are invalid.
102
103
104# 9. Indent
105
106Please use TAB or 4 spaces to indent. It's preferred to use 4 spaces. If no
107other special meanings, the indent should begin right after "{":
108
109    if (condition)
110    {
111        /* others */
112    }
113
114The only one exception is switch. In case statements for switches, "case" should be
115aligned with "switch":
116
117    switch (value)
118    {
119    case value1:
120        break;
121    }
122
123"case" is aligned with "switch". The following code block should be indented.
124
125
126# 10. Braces and Spaces
127
128For ease of reading, it is advised that braces should occupy the whole line
129instead of following other statements. Like:
130
131    if (condition)
132    {
133        /* others */
134    }
135
136When matching braces have their own lines, the reader identifies the code
137blocks easily.
138
139There should be a space before parentheses when it's not a function call. For
140example:
141
142    if (x <= y)
143    {
144        /* others */
145    }
146
147    for (index = 0; index < MAX_NUMBER; index ++)
148    {
149        /* others */
150    }
151
152In expressions, there should be a space between most binary and ternary
153operators and the strings. There should be no spaces around(inside) parentheses, like:
154
155    if ( x <= y )
156    {
157        /* other */
158    }
159
160This is a bad practice.
161
162
163# 11. trace, log Information
164
165In RT-Thread, rt_kprintf is a commonly used logging routine. In RT-Thread
166rt_kprintf is implemented as a polling, non-interrupting string output. It is
167suitable in "instant" situations such as interrupt context. The polling method
168would have influence to the timing sequence of the log output.
169
170It is not recommended to use rt_kprintf frequently. Please be aware that frequen
171use will make your code run slower.
172
173Logging should be off by default and can be turned on by a switch (e.g. a
174variable or a macro). When logging, it should be easy to understand and easy to
175determine where the problem is.
176
177
178# 12. Functions
179
180Functions in kernel should be K.I.S.S. ("Keep it simple, stupid.") If the function
181is too long, you should split it into smaller ones, with each of them simplified to
182be easy to understand.
183
184
185# 13. Objects
186
187The kernel of RT-Thread uses object-oriented techniques in C. The naming convention
188is: structure names are the object names, object names + verb phrases are the
189method names of objects:
190
191    struct rt_timer
192    {
193        struct rt_object parent;
194        /* other fields */
195    };
196    typedef struct rt_timer* rt_timer_t;
197
198The definition of structure rt_timer stands for the object definition of timer
199object.
200
201    rt_timer_t rt_timer_create(const char* name,
202        void (*timeout)(void* parameter), void* parameter,
203        rt_tick_t time, rt_uint8_t flag);
204    rt_err_t rt_timer_delete(rt_timer_t timer);
205    rt_err_t rt_timer_start(rt_timer_t timer);
206    rt_err_t rt_timer_stop(rt_timer_t timer);
207
208rt_timer + verb phrase stands for the method that could be used on a timer object.
209
210When creating a new object, think twice on memory allocations: whether a static
211object could be created or it could only created dynamically on the heap. Allocations
212can be slower, but may be necessary in dynamic environments.
213
214# 14. Use astyle to format the code automatically
215parameters: --style=allman
216            --indent=spaces=4
217            --indent-preproc-block
218            --pad-oper
219            --pad-header
220            --unpad-paren
221            --suffix=none
222            --align-pointer=name
223            --lineend=linux
224            --convert-tabs
225            --verbose
226
227