分析一套源代碼的代碼規範和風格並討論如何改進優化代碼

1.開發步驟

本次工程實踐是基於ESP-WROVER-KIT開發板的數據採集系統，ESP32開發板經過 USB 鏈接到開發主機（開發主機能夠是 Linux、Windows 或MacOS操做系統），開發主機上有 ESP-IDF (樂鑫 SDK)、編譯器工具鏈和項目代碼。主機先編譯代碼生成可執行文件，而後電腦上的工具把生成的文件燒到板子上，而後板子開始執行文件，最後經過超級終端你能夠從主機查看日誌。因爲交叉編譯環境搭好以後，樂鑫提供了不少源碼，主要是C語言寫的代碼。故從樂鑫的ESP-IDF中找出一套WIFI相關的源代碼進行分析。

2.分析源代碼目錄結構

從樂鑫的ESP-IDF下載的WIFI模塊，由許多小的模塊組成，共同實現WIFI功能。包括低功耗模塊，探測模塊，文字處理模塊，每一個模塊命名採用簡單易懂，描述命名規則的名字來替代。在開發前先看下README，對整個WIFI模塊的實現有個大體的瞭解。

• WiFi爲整個源代碼包的名稱，由目錄模塊可知，WiFi由不少小的模塊組成，包括低功耗，探測網絡信號等，本次主要分析其中的Getting_started下的c語言代碼，其他模塊代碼結構風格相似。

　　每一個小模塊的代碼目錄結構：

• main存放項目的全部源代碼
• Makefile文件:文件中包含項目的編譯信息
• CMakeLists.txt:存放Cmake編譯信息
• build:存放項目構建所必須的庫

3. 文件名、類名、函數名、變量名等命名

• 函數名

和變量同樣，函數名稱也應具備說明性。函數名應使用動詞或動做性名字, 採用Snake Case命名法，這是書寫複合詞或短語的一種慣例（practice）。複合詞或短語中的各個單詞之間用 下劃線 （_）分隔而且沒有空格。複合詞中的每個單詞的首字母一般都是小寫的，而且複合詞的第一個字母既能夠是大寫的又能夠是小寫的，例如：「foo_bar」和「Hello_world」。通常認爲 Snake Case 的可讀性要比 Camel Case 要強。

• 變量名

變量命名分爲兩種，對於普通變量，也採用下劃線鏈接單詞的命名方法，變量名爲小寫，對於宏定義，命名規則與普通變量命名相同，可是卻換成了大寫字母，以便於區分。

 

4.接口定義規範　

即一些預先定義的函數，目的是提供應用程序與開發人員基於某軟件或硬件得以訪問一組例程的能力，而又無需訪問源碼，或理解內部工做機制的細節。實現一組函數供別人使用，就是提供接口；使用別人提供的函數，就是調用接口。在下載的源碼包中，將代碼實現和接口申明放在兩個文件下。方便用戶的使用，同時代碼簡潔，方便用戶閱讀。

在編寫代碼加載頭文件

             

五、項目代碼風格

• 註釋

因爲項目比較大，故寫每個模塊的時候都有註釋，方便閱讀和使用接口，以及項目的對接。

 

• 代碼縮進

良好的代碼縮進能展現出代碼的邏輯，方便閱讀和理解。

• 代碼實現和接口分開

6．模塊測試

每一個模塊都須要測試，測試的方法有不少，本項目能夠經過添加printf語句輸出進行測試.

7、列舉哪些作法有悖於「代碼的簡潔、清晰、無歧義」的基本原則

• 命名不夠嚴謹，直接A,B,C，不方便閱讀
• 沒有寫註釋，別人很難看懂你的代碼
• 沒有縮進，代碼一團亂，找不出代碼邏輯
• 開發文檔沒有，項目很難被接手
• 在不一樣的代碼風格中, 語言內置關鍵字和符號周圍會分佈有不一樣數量的空格, 沒有使用空格

8、總結同類編程語言或項目在代碼規範和風格的通常要求

• 1) 空行

空行起着分隔程序段落的做用。空行得體將使程序的佈局更加清晰。空行不會浪費內存，雖然打印含有空行的程序會多消耗一些紙張，可是值得。
規則一：定義變量後要空行。儘量在定義變量的同時初始化該變量，即遵循就近原則。若是變量的引用和定義相隔比較遠，那麼變量的初始化就很容易被忘記。若引用了未被初始化的變量，就會致使程序出錯。
規則二：每一個函數定義結束以後都要加空行。
總規則：兩個相對獨立的程序塊、變量說明以後必需要加空行。好比上面幾行代碼完成的是一個功能，下面幾行代碼完成的是另外一個功能，那麼它們中間就要加空行。這樣看起來更清晰。

• 2) 空格

規則一：關鍵字以後要留空格。像 const、case 等關鍵字以後至少要留一個空格，不然沒法辨析關鍵字。像 if、for、while 等關鍵字以後應留一個空格再跟左括號(，以突出關鍵字。
規則二：函數名以後不要留空格，應緊跟左括號(，以與關鍵字區別。
規則三：(向後緊跟；)、,、;這三個向前緊跟；緊跟處不留空格。
規則四：,以後要留空格。若是;不是一行的結束符號，其後要留空格。
規則五：賦值運算符、關係運算符、算術運算符、邏輯運算符、位運算符，如 =、==、！=、+=、－=、*=、/=、%=、>>=、<<=、&=、^=、|=、>、<=、>、>=、+、－、*、/、%、&、|、&&、||、<<、>>、^ 等雙目運算符的先後應當加空格。
注意，運算符「%」是求餘運算符，與 printf 中 %d 的「%」不一樣，因此 %d 中的「%」先後不用加空格。
規則六：單目運算符 !、~、++、－－、－、*、& 等先後不加空格。
注意：

• 這裏的「－」和規則五里面的「－」不一樣。這裏的「－」是負號運算符，規則五里面的「－」是減法運算符。
• 這裏的「*」和規則五里面的「*」也不一樣。這裏的「*」是指針運算符，規則五里面的「*」是乘法運算符。
• 這裏的「&」和規則五里面的「&」也不一樣。這裏的「&」是取地址運算符，規則五里面的「&」是按位與運算符。
• 總之，規則六中的是單目運算符，而規則五中的是雙目運算符，它們是不同的。

規則七：像數組符號[]、結構體成員運算符.、指向結構體成員運算符->，這類操做符先後不加空格。
規則八：對於表達式比較長的 for 語句和 if 語句，爲了緊湊起見，能夠適當地去掉一些空格。但 for 和 if 後面緊跟的空格不能夠刪，其後面的語句能夠根據語句的長度適當地去掉一些空格。例如：

 for (i=0; i<10; i++) for 和分號後面保留空格就能夠了，=和<先後的空格可去掉。

•  3) 成對書寫

成對的符號必定要成對書寫，如 ()、{}。不要寫完左括號而後寫內容最後再補右括號，這樣很容易漏掉右括號，尤爲是寫嵌套程序的時候。

• 4) 縮進

縮進是經過鍵盤上的 Tab 鍵實現的，縮進可使程序更有層次感。原則是：若是地位相等，則不須要縮進；若是屬於某一個代碼的內部代碼就須要縮進。

• 5) 對齊

對齊主要是針對大括號{}說的：
規則一：{和}分別都要獨佔一行。互爲一對的{和}要位於同一列，而且與引用它們的語句左對齊。
規則二：{}以內的代碼要向內縮進一個 Tab，且同一地位的要左對齊，地位不一樣的繼續縮進。
還有須要注意的是，不少編程軟件是會「自動對齊」的，好比：

#include <stdio.h>
int main(void)
{
    if (…)
    return 0;
}

寫完 if 那一行後，按回車，此時光標在括號的右邊，而此 if 下的大括號要寫在與 if 左對齊的正下方，一般咱們是按一下 Backspace 鍵使光標停在與 if 左對齊的正下方。但事實上咱們不須要這樣作，咱們直接輸入大括號便可，系統會自動對齊到與 if 左對齊的正下方。再接着看：

#include <stdio.h>
int main(void)
{
    if (…)
    {
        while (…)
    }
    return 0;
}

寫完 while 那一行後，按回車，此時光標不是停在與 while 左對齊的正下方，一樣，咱們不須要按 Backspace，直接輸入大括號便可，系統會自動對齊到與 while 左對齊的正下方的。
此外編程軟件還有「對齊、縮進修正」功能。就是按 Ctrl+A 全選，而後按 Alt+F8，這時程序中全部成對的大括號都會自動對齊，未縮進的也會自動縮進。不論是在編程過程當中，仍是在編寫結束完以後，均可以使用這個技巧。但若是徹底按照規範寫，那根本就不須要這個技巧，因此，這只是一個輔助功能。

• 6) 代碼行

規則一：一行代碼只作一件事情，如只定義一個變量，或只寫一條語句。這樣的代碼容易閱讀，而且便於寫註釋。
規則二：if、else、for、while、do 等語句自佔一行，執行語句不得緊跟其後。此外，很是重要的一點是，不論執行語句有多少行，就算只有一行也要加{}，而且遵循對齊的原則，這樣能夠防止書寫失誤。

• 7) 註釋

C語言中一行註釋通常採用//…，多行註釋必須採用/*…*/。註釋一般用於重要的代碼行或段落提示。在通常狀況下，源程序有效註釋量必須在 20% 以上。雖然註釋有助於理解代碼，但注意不可過多地使用註釋。
規則一：註釋是對代碼的「提示」，而不是文檔。程序中的註釋不可喧賓奪主，註釋太多會讓人眼花繚亂。
規則二：若是代碼原本就是清楚的，則沒必要加註釋。例如：

i++;  //i加1

這個就是多餘的註釋。
規則三：邊寫代碼邊註釋，修改代碼的同時要修改相應的註釋，以保證註釋與代碼的一致性，再也不有用的註釋要刪除。
規則四：當代碼比較長，特別是有多重嵌套的時候，應當在段落的結束處加註釋，這樣便於閱讀。
規則五：每一條宏定義的右邊必需要有註釋，說明其做用。