RT-Thread 開發(fā)的目錄名稱與文件名稱

這是一份 RT-Thread 開發(fā)人員的開發(fā)指引。RT-Thread 做為一份開源軟件，它需要由不同 的人采用合作的方式完成，這份文檔是開發(fā)人員的一個指引。RT-Thread 的開發(fā)人員請遵 守這樣的編程風(fēng)格。同時對于使用 RT-Thread 的用戶，也可通過這份文檔了解 RT-Thread 代碼內(nèi)部一些約定從而比較容易的把握到 RT-Thread 的實現(xiàn)方式。

1.目錄名稱

目錄名稱如果無特殊的需求，請使用全小寫的形式；目錄名稱應(yīng)能夠反應(yīng)部分的意思，例 如各芯片移植由其芯片名稱構(gòu)成或芯片類別構(gòu)成；components 目錄下能夠反映組件的意義。

2.文件名稱

文件名稱如果無特殊的需求（如果是引用其他地方，可以保留相應(yīng)的名稱），請使用全小寫 的形式。另外為了避免文件名重名的問題，一些地方請盡量不要使用通用化、使用頻率高 的名稱。

3.頭文件定義

C語言頭文件為了避免多次重復(fù)包含，需要定義一個符號。這個符號的定義形式請采用如下 的風(fēng)格：

1 #ifndef __FILE_H__

2 #define __FILE_H__

3 /* header file content */

4 #endif

即定義的符號兩側(cè)采用 “__” 以避免重名，另外也可以根據(jù)文件名中是否包含多個詞語而 采用 “_” 連接起來。

4.文件頭注釋

在每個源文件文件頭上，應(yīng)該包括相應(yīng)的版權(quán)信息，Change Log 記錄：

1 /*

2 * File ： rtthread.h

3 * This file is part of RT-Thread RTOS

4 * COPYRIGHT （C） 2006 - 2012， RT-Thread Development Team

5 *

6 * This program is free software; you can redistribute it and/or modify

7 * it under the terms of the GNU General Public License as published by

8 * the Free Software Foundation; either version 2 of the License， or

9 * （at your option） any later version.

10 *

11 * This program is distributed in the hope that it will be useful，

12 * but WITHOUT ANY WARRANTY; without even the implied warranty of

13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the

14 * GNU General Public License for more details.

15 *

16 * You should have received a copy of the GNU General Public License along

17 * with this program; if not， write to the Free Software Foundation， Inc.，

18 * 51 Franklin Street， Fifth Floor， Boston， MA 02110-1301 USA.

19 *

20 * Change Logs：

21 * Date Author Notes

22 * 2006-03-18 Bernard the first version

23 * 2006-04-26 Bernard add semaphore APIs

24 * 。..

25 */

例如采用如上的形式。

5.結(jié)構(gòu)體定義

結(jié)構(gòu)體名稱請使用小寫英文名的形式，單詞與單詞之間采用 “_” 連接，例如：

1 struct rt_list_node

2 {

3 struct rt_list_node *next;

4 struct rt_list_node *prev;

5 };

其中，“{”，“}” 獨立占用一行，后面的成員定義使用縮進(jìn)的方式定義。

結(jié)構(gòu)體等的類型定義請以結(jié)構(gòu)體名稱加上 “_t” 的形式作為名稱，例如：

1 typedef struct rt_list_node rt_list_t;

因為內(nèi)核中對象引用方便的緣故，采用了對象內(nèi)核指針作為類型定義的形式，例如：

1 typedef struct rt_timer* rt_timer_t;

6.宏定義

在RT-Thread中，請使用大寫英文名稱作為宏定義，單詞之間使用 “_” 連接，例如：

向滑動查看全部

1 #define RT_TRUE 1

7.函數(shù)名稱、聲明

函數(shù)名稱請使用小寫英文的形式，單詞之間使用 “_” 連接。提供給上層應(yīng)用使用的 API 接口，必須在相應(yīng)的頭文件中聲明；如果函數(shù)入口參數(shù)是空，必須使用 void 作為入口參 數(shù)，例如：

1 rt_thread_t rt_thread_self（void）;

8.注釋編寫

請使用英文做為注釋，使用中文注釋將意味著在編寫代碼時需要來回不停的切換中英文輸 入法從而打斷編寫代碼的思路。并且使用英文注釋也能夠比較好的與中國以外的技術(shù)者進(jìn) 行交流。

源代碼的注釋不應(yīng)該過多，更多的說明應(yīng)該是代碼做了什么，僅當(dāng)個別關(guān)鍵點才需要一些 相應(yīng)提示性的注釋以解釋一段復(fù)雜的算法它是如何工作的。對語句的注釋只能寫在它的上 方或右方，其他位置都是非法的。

9.縮進(jìn)及分行

縮進(jìn)請采用 4 個空格的方式。如果沒有什么特殊意義，請在 “{” 后進(jìn)行分行，并在下一 行都采用縮進(jìn)的方式，例如：

1 if （condition）

2 {

3 /* others */

4 }

唯一的例外是 switch 語句，switch-case 語句采用 case 語句與 switch 對齊的方式， 例如：

1 switch （value）

2 {

3 case value1：

4 break;

5 }

case 語句與前面的 switch 語句對齊，后續(xù)的語句則采用縮進(jìn)的方式。

分行上，如果沒有什么特殊考慮，請不要在代碼中連續(xù)使用兩個以上的空行。

10.大括號與空格

從代碼閱讀角度，建議每個大括號單獨占用一行，而不是跟在語句的后面，例如：

1 if （condition）

2 {

3 /* others */

4 }

匹配的大括號單獨占用一行，代碼閱讀起來就會有相應(yīng)的層次而不會容易出現(xiàn)混淆的情況。

空格建議在非函數(shù)方式的括號調(diào)用前留一個空格以和前面的進(jìn)行區(qū)分，例如：

1 if （x 《= y）

2 {

3 /* others */

4 }

5

6 for （index = 0; index 《 MAX_NUMBER; index ++）

7 {

8 /* others */

9 }

建議在括號前留出一個空格（涉及的包括 if、for、while、switch 語句），而運(yùn)算表達(dá)式 中，運(yùn)算符與字符串間留一個空格。另外，不要在括號的表達(dá)式兩側(cè)留空格，例如：

1 if （ x 《= y ）

2 {

3 /* other */

4 } /* others */

5 }

這樣括號內(nèi)兩側(cè)的空格是不允許的。

11.trace、log信息

在 RT-Thread 中，普遍使用的 log 方式是 rt_kprintf。rt_kprintf 在 RT-Thread 被實 現(xiàn)成一個采用輪詢、非中斷方式的字串輸出，能夠適合于在中斷這類“即時”顯示日志的場 合。因為這種輪詢方式的存在，也必然會影響到日志輸出的時序關(guān)系。

建議在代碼中不要頻繁的使用 rt_kprintf 作為日志輸出，除非你真正的明白，你的代碼 運(yùn)行占用的時間多一些也沒什么關(guān)系。

日志輸出應(yīng)該被設(shè)計成正常情況下是關(guān)閉狀態(tài)（例如通過一個變量或宏就能夠開啟），并且 當(dāng)真正輸出日志時，日志是易懂易定位問題的方式?！疤鞎健钡娜罩鞠到y(tǒng)是糟糕的，不合 理的。

12.函數(shù)

在內(nèi)核編程中，函數(shù)應(yīng)該盡量精簡，僅完成相對獨立的簡單功能。函數(shù)的實現(xiàn)不應(yīng)該太長 ，函數(shù)實現(xiàn)太長，應(yīng)該反思能夠如何修改（或拆分）使得函數(shù)更為精簡、易懂。

13.對象

RT-Thread 內(nèi)核采用了 C 語言對象化技術(shù)，命名表現(xiàn)形式是：對象名結(jié)構(gòu)體表示類定義、 對象名 + 動詞短語形式表示類方法，例如：

1 struct rt_timer

2 {

3 struct rt_object parent;

4 /* other fields */

5 };

6 typedef struct rt_timer* rt_timer_t;

結(jié)構(gòu)體定義 rt_timer 代表了 timer 對象的類定義；

1 rt_timer_t rt_timer_create（const char* name，

2 void （*timeout）（void* parameter）， void* parameter，

3 rt_tick_t time， rt_uint8_t flag）;

4 rt_err_t rt_timer_delete（rt_timer_t timer）;

5 rt_err_t rt_timer_start（rt_timer_t timer）;

6 rt_err_t rt_timer_stop（rt_timer_t timer）;

rt_timer + 動詞短語的形式表示能夠應(yīng)用于 timer 對象的方法。

在創(chuàng)建一個新的對象時，應(yīng)該思考好，對象的內(nèi)存操作處理：是否允許一個靜態(tài)對象存在 ，或僅僅支持從堆中動態(tài)分配的對象。
責(zé)任編輯:pj