[C/C++/嵌入式]嵌入式C編程的風格規範

 嵌入式C編程的風格規範

一、概述
 本文檔描述在嵌入式開發中，C語言編程中應該注意的編程風格；力圖使不同的模組，
 不同人員編寫的程式具有類似的風格，為程式方便維護打下基礎。
 針對人員：所有參與C編程的開發人員。

二、檔案組織和結構
 1.1 檔案組織
  一般在設計時就確定了系統的模組，並注重確定每個模組的介面部分，每個模組
  我們用兩個檔案編寫：.H和.C。
  .H是模組的介面部分，只允許放置：
  1）本模組公開的函式宣告；
  2）本模組公開的全域變數聲明；
  3）本模組公開的資料結構定義（即別的模組可能用到的struct）；
  4）本模組公開的宏定義；在其他模組中可能要引用的宏，如CHANNLE_MAXCOUNT；
  5）其他的所有本模組的局部模組變數，模組內建函式不允許在.H中聲明；
  
  .C是模組的實現部分，可以自由定義：
  1）本模組所需的模組變數；
  2）僅供本模組使用的局部模組函數；如果覺得可以作為必要的函數庫，可以單獨
     寫個模組，使其成為公用的函數庫；
  3）.H中聲明函數的實現部分；
 1.2 檔案結構
  每個.C檔案分下面幾個部分組成：
  1）著作權說明，檔案說明；格式如下例：
   /*
    * comm.c This module implements the serial communication, include
    *   above layer 's bussiness
    *
    * Version: @(#)comm.c 1.0.1.1 2005-3-19
    *
    * Authors: VictorPANG, <shenglipang@163.com>
    *
    * Fixes:
    *  VictorPANG : Refix it. 2005-4-6
    *  WangJianFeng: Fill the file. 2005-4-6
    *  VictorPANG :  Create the file but not fill it. 2005-03-19.
    */
   
  2）include部分
   //includes...
   //-----------
   #include <stdio.h>
   #include <stdlib.h>
   #include <string.h>
   
   #include "com.h"
   #include "mcu.h"
   
   首先包含標準庫標頭檔，用角括弧包含<>；
   空行後再寫本工程的標頭檔，用雙引號包含""；
   
  3）const部分
   定義本檔案需要的常量和宏，格式如下：
   //consts...
   //---------
   const int PHONE_MAXCOUNT = 128;
   
   #define READ_1302(reg) *((unsigned char xdata *)0x8000+reg)
   
   注意：常量定義可以在使用前才定義，可能的話集中放置於此，如果方便可以
   使用前才定義。
  
  4）資料結構定義部分
   定義本模組使用的資料結構，如：
   typedef struct hub_macframe
   {
    uchar channelid;
    union{
    uint  beginpos1;
    uchar memindex1;
    }u1;
    union{
    uint endpos1;
    uint length1;
    }u2;
   
    //frame header
    uchar sourceadd;
    uchar destadd;
    uchar headchk;
    uchar chkcorrect;
   
    
    struct hub_macframe xdata *next;
    //use to indicate it's parent,when insert into send list,
    //if insert method is copy, we increase frame's ref,and set new
    //frame's parent to its parent
    struct hub_macframe xdata *parent;
    
   #define beginpos u1.beginpos1
   #define memindex u1.memindex1
   #define endpos   u2.endpos1
   #define length   u2.length1
   }hub_macframe;
   
   注意：我們提倡使用資料結構（struct）組織關係緊密的各種資料，不提倡用
   零散的變數表示事物；往往一個事物可以用一個struct可以表示他的所有屬性。
   
  5）模組變數定義部分
   在定義了資料結構後，可以在本部分定義模組中需要的全域變數。如：
   //global values...
   //----------------
   objectpool data hub_framepool;

  5）模組私人函數定義部分
   本部分定義只有本模組調用的函數，稱為模組私人函數。
   
  6）模組介面函數實現部分
   本部分定義（實現）.H中聲明的介面函數。

三、標識符
 標識符是檔案名稱、變數名、常量名、函數名、數組名、子程式名、類型名等使用者定義的
 名稱的總稱。
 我們約定以下幾點：
 1）變數名、函數名、數組名、子程式名一律用小寫字母命名；常量名盡量用大寫字母命名；
 2）名稱的選擇。模組確定後它內部的函數名、子程式名、模組（全域）變數的命名均為
    模組名_標識符。如com_send_message，com_receive_data，com_entity等。
    對模組內函數中的局部變數的命名，不做要求。
 3）標識符應該能正確表達它的含義，杜絕全域變數中使用i,j等沒有任何含義的名稱。
 4）標識符不必太長，如果太短表達不清，可以適當加長，並用底線分割各個單詞，如：
    com_send_message, phone_query_channel_state(char chnid)等。

 
四、注釋
 可以視情況編寫注釋，但要求模組的介面部分必須有注釋。
 注釋一般在所注釋對象的前面或並行部分。
 到底使用//和/* */不做要求。

 
五、視覺組織
 5.1 程式碼
  規則如下：
  1）一行代碼只做一件事情，如只定義一個變數，或唯寫一條語句。這樣的代碼容易
     閱讀，並且方便於寫注釋。
  2）if、for、while、do等語句自佔一行，執行語句不得緊跟其後。不論執行語句有
     多少都要加{}（即使只有一行也要加上）。這樣可以防止書寫失誤。
 5.2 空格
  規則如下：
  1）關鍵字之後要留空格。象const、virtual、inline、case 等關鍵字之後至少要留
     一個空格，否則無法辨析關鍵字。象if、for、while等關鍵字之後應留一個空格再
     跟左括弧'（'，以突出關鍵字。
  2）函數名之後不要留空格，緊跟左括弧'（'，以與關鍵字區別。
  3）'（'向後緊跟，'）'、'，'、';'向前緊跟，緊跟處不留空格。
  4）'，'之後要留空格，如Function(x, y, z)。如果';'不是一行的結束符號，其後要
     留空格，如for (initialization; condition; update)。
  5）賦值操作符、比較操作符、算術操作符、邏輯操作符、位網域作業符，如"="、"+="
     ">="、"<="、"+"、"*"、"%"、"&&"、"||"、"<<","^"等二元操作符的前後應當加
     空格。
  6）一元操作符如"!"、"~"、"++"、"--"、"&"（地址運算子）等前後不加空格。
  7）象"［］"、"."、"->"這類操作符前後不加空格。
  8）對於運算式比較長的for語句和if語句，為了緊湊起見可以適當地去掉一些空格，
     如for (i=0; i<10; i++)和if ((a<=b) && (c<=d))。
 5.3 空行
  空行起著分隔程式段落的作用。空行得體（不過多也不過少）將使程式的布局更加清晰。
  空行不會浪費記憶體，雖然列印含有空行的程式是會多消耗一些紙張，但是值得。所以不
  要捨不得用空行。
  規則如下：
  1）在每個類、結構體聲明之後、每個函數定義結束之後都要加空行。
     如：函數間的空行。
   // 空行
   void Function1(…)
   {
    …
   }
   // 空行
   void Function2(…)
   {
     …
   }
   // 空行
   void Function3(…)
   {
     …
   }
  2）在一個函數體內，邏輯上密切相關的語句之間不加空行，其它地方應加空行分隔。
     如：函數內部的空行。
   // 空行
   while (condition)
   { 
    statement1; 
    // 空行 
    if (condition)  
    {  
     statement2; 
    } 
    else 
    {  
     statement3; 
    }
    // 空行 
    statement4;
   }
 5.4 縮排
  規則如下：
  1）程式的分界符'{'和'}'應獨佔一行並且位於同一列，同時與引用它們的語句靠左對齊。
  2）{ }之內的代碼塊在'{'右邊數格處靠左對齊。我們規定用Tab鍵對齊，一個Tab鍵為4個
     空格寬度。
     嵌套的｛｝，則使用縮排對齊，如： 
     {
         …  
         {
           …  
         }
         …
     }

 -------------------------------------------------------------
 |     修改人   |    修改時間   |    版本   |    修改項   |
 -------------------------------------------------------------
 |   VictorPANG |    2005-4-6 |  V1.0.1.1 |  建立、編寫 |
 -------------------------------------------------------------