C語言常用的編程規範

標籤：時間   函數   編輯器   2-2   des   block   switch   create   ...   

1排版

1-1相對獨立的程式塊之間、變數說明之後必須加空行。
樣本：如下例子不符合規範。
if (!valid_ni(ni))
{
... // program code
}
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
應如下書寫
if (!valid_ni(ni))
{
... // program code
}
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
1-2：較長的語句（>80 字元）要分成多行書寫，長運算式要在低優先順序操作符處劃分新行，
操作符放在新行之首，劃分出的新行要進行適當的縮排，使排版整齊，語句可讀。
樣本：
perm_count_msg.head.len = NO7_TO_STAT_PERM_COUNT_LEN

• STAT_SIZE_PER_FRAM * sizeof( _UL );
  act_task_table[frame_id * STAT_TASK_CHECK_NUMBER + index].occupied
  = stat_poi[index].occupied;
  act_task_table[taskno].duration_true_or_false
  = SYS_get_sccp_statistic_state( stat_item );
  report_or_not_flag = ((taskno < MAX_ACT_TASK_NUMBER)
  && (n7stat_stat_item_valid (stat_item))
  && (act_task_table[taskno].result_data != 0));
  1-3：不允許把多個短語句寫在一行中，即一行唯寫一條語句。
  樣本：如下例子不符合規範。
  rect.length = 0; rect.width = 0;
  應如下書寫
  rect.length = 0;
  rect.width = 0;
  1-4： if、 for、 do、 while、 case、 switch、 default 等語句自佔一行，且 if、 for、 do、 while
  等語句的執行語句部分無論多少都要加括弧{}。
  樣本：如下例子不符合規範。
  if (pUserCR == NULL) return;
  應如下書寫：
  if (pUserCR == NULL)
  {
  return;
  }
  1-5：對齊只使用空格鍵，不使用 TAB 鍵。
  說明：以免用不同的編輯器閱讀程式時，因 TAB 鍵所設定的空格數目不同而造成程式布局
  不整齊，不要使用 BC 作為編輯器合版本，因為 BC 會自動將 8 個空格變為一個 TAB 鍵，
  因此使用 BC 合入的版本大多會將縮排變亂。
  1-6：程式塊的分界符（如 C/C++語言的大括弧‘{’和‘}’）應各獨佔一行並且位於同一列，
  同時與引用它們的語句靠左對齊。在函數體的開始、類的定義、結構的定義、枚舉的定義以
  及 if、 for、 do、 while、 switch、 case 語句中的程式都要採用如上的縮排方式。
  樣本：如下例子不符合規範。
  for (...) {
  ... // program code
  }
  if (...)
  {
  ... // program code
  }
  void example_fun( void )
  {
  ... // program code
  }
  應如下書寫。
  for (...)
  {
  ... // program code
  }
  if (...)
  {
  ... // program code
  }
  void example_fun( void )
  {
  ... // program code
  }
  1-7：一行程式以小於 80 字元為宜，不要寫得過長。

2 注釋

2-1：一般情況下，來源程式有效注釋量必須在 20％以上。
說明：注釋的原則是有助於對程式的閱讀理解，在該加的地方都加了，注釋不宜太多也不能
太少，注釋語言必須準確、易懂、簡潔。
2-2：邊寫代碼邊注釋，修改代碼同時修改相應的注釋，以保證注釋與代碼的一致性。不再
有用的注釋要刪除。
2-3：注釋應與其描述的代碼相近，對代碼的注釋應放在其上方或右方（對單條語句的注釋）
相鄰位置，不可放在下面，如放於上方則需與其上面的代碼用空行隔開。
樣本：如下例子不符合規範。
例 1：
/* get replicate sub system index and net indicator */

repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
例 2：
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
/* get replicate sub system index and net indicator /
應如下書寫
/ get replicate sub system index and net indicator /
repssn_ind = ssn_data[index].repssn_index;
repssn_ni = ssn_data[index].ni;
2-4：對於所有有物理含義的變數、常量，如果其命名不是充分自注釋的，在聲明時都必須
加以注釋，說明其物理含義。變數、常量、宏的注釋應放在其上方相鄰位置或右方。
樣本：
/ active statistic task number */

define MAX_ACT_TASK_NUMBER 1000define MAX_ACT_TASK_NUMBER 1000 /* active statistic task number /
2-5：注釋與所描述內容進行同樣的縮排。
說明：可使程式排版整齊，並方便注釋的閱讀與理解。
樣本：如下例子，排版不整齊，閱讀稍感不方便。
void example_fun( void )
{
/ code one comments /
CodeBlock One
/ code two comments /
CodeBlock Two
}
應改為如下布局。
void example_fun( void )
{
/ code one comments /
CodeBlock One
/ code two comments /
CodeBlock Two
}
2-6：在程式塊的結束行右方加註釋標記，以表明某程式塊的結束。
說明：當程式碼片段較長，特別是多重嵌套時，這樣做可以使代碼更清晰，更便於閱讀。
樣本：參見如下例子。
if (...)
{
// program code
while (index < MAX_INDEX)
{
// program code
} / end of while (index < MAX_INDEX) / // 指明該條 while 語句結束
} / end of if (...) / // 指明是哪條 if 語句結束
2-7：注釋格式盡量統一，建議使用“/ …… */”。
2-8：注釋應考慮程式易讀及外觀排版的因素，使用的語言若是中、英兼有的，建議多使用
中文，除非能用非常流利準確的英文表達。
說明：注釋語言不統一，影響程式易讀性和外觀排版，出於對維護人員的考慮，建議使用中
文。

3 標識符命名

3-1：標識符的命名要清晰、明了，有明確含義，同時使用完整的單詞或大家基本可以理解
的縮寫，避免使人產生誤解。
說明：較短的單詞可通過去掉“母音”形成縮寫；較長的單詞可取單詞的頭幾個字母形成縮
寫；一些單詞有大家公認的縮寫。
樣本：如下單詞的縮寫能夠被大家基本認可。
temp 可縮寫為 tmp ;
flag 可縮寫為 flg ;
statistic 可縮寫為 stat ;
increment 可縮寫為 inc ;
message 可縮寫為 msg ;
3-2：命名中若使用特殊約定或縮寫，則要有注釋說明。
說明：應該在源檔案的開始之處，對檔案中所使用的縮寫或約定，特別是特殊的縮寫，進行
必要的注釋說明。
3-3：自己特有的命名風格，要自始至終保持一致，不可來回變化。
說明：個人的命名風格，在符合所在項目組或產品組的命名規則的前提下，才可使用。（即
命名規則中沒有規定到的地方才可有個人命名風格）。
3-4：對於變數命名，禁止取單個字元（如 i、 j、 k...），建議除了要有具體含義外，還能表
明其變數類型、資料類型等，但 i、 j、 k 作局部迴圈變數是允許的。
說明：變數，尤其是局部變數，如果用單個字元表示，很容易敲錯（如 i 寫成 j），而編譯時間
又檢查不出來，有可能為了這個小小的錯誤而花費大量的查錯時間。
樣本：下面所示的局部變數名的定義方法可以借鑒。
int liv_Width
其變數名解釋如下：
l 局部變數（Local） （其它： g 全域變數（Global） ...）
i 資料類型（Interger）
v 變數（Variable） （其它： c 常量（Const） ...）
Width 變數含義
這樣可以防止局部變數與全域變數重名。
3-5：命名規範必須與所使用的系統風格保持一致，並在同一項目中統一，比如採用 UNIX
的全小寫加底線的風格或大小寫混排的方式，不要使用大小寫與底線混排的方式，用
作特殊標識如標識成員變數或全域變數的 m_和 g_，其後加上大小寫混排的方式是允許的。
樣本： Add_User 不允許， add_user、 AddUser、 m_AddUser 允許。
3-6：在同一軟體產品內，應規劃好介面部分標識符（變數、結構、函數及常量）的命名，
防止編譯、連結時產生衝突。
說明：對介面部分的標識符應該有更嚴格限制，防止衝突。如可規定介面部分的變數與常量
之前加上“模組”標識等。
3-7：用正確的反義片語命名具有互斥意義的變數或相反動作的函數等。
說明：下面是一些在軟體中常用的反義片語。
add / remove begin / end create / destroy
insert / delete first / last get / release
increment / decrement put / get
add / delete lock / unlock open / close
min / max old / new start / stop
next / previous source / target show / hide
send / receive source / destination
cut / paste up / down
樣本：
int min_sum;
int max_sum;
int add_user( BYTE user_name );
int delete_user( BYTE user_name );

4 可讀性

4-1：注意運算子的優先順序，並用括弧明確運算式的操作順序，避免使用預設優先順序。
4-2：函數的規模盡量限制在 200 行以內。

C語言常用的編程規範