[編程技巧]編程規范與范例(1)
程序匠人 發表于 2005-8-27 20:14:00       閱讀全文(340) | 回復(0) | 引用(0) 
編程規范與范例(1)  
〖文章轉載或出處〗≡中國電子技術信息網≡ 網址：www.CETINet.com 
編程規范與范例(1)

目  錄
1 排版 6
2 注釋 11
3 標識符命名 18
4 可讀性 20
5 變量、結構 22
6 函數、過程 28
7 可測性 36
8 程序效率 40
9 質量保證 44
10 代碼編輯、編譯、審查 50
11 代碼測試、維護 52
12 宏 53
 
1 排版
¹ 1-1：程序塊要采用縮進風格編寫，縮進的空格數為4個。
說明：對于由開發工具自動生成的代碼可以有不一致。
¹ 1-2：相對獨立的程序塊之間、變量說明之后必須加空行。
示例：如下例子不符合規范。
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-3：較長的語句（>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));
 
&sup1; 1-4：循環、判斷等語句中若有較長的表達式或語句，則要進行適應的劃分，長表達式要在低優先級操作符處劃分新行，操作符放在新行之首。
示例：
if ((taskno < max_act_task_number)
    && (n7stat_stat_item_valid (stat_item)))
{
    ... // program code
}

for (i = 0, j = 0; (i < BufferKeyword[word_index].word_length)
                    && (j < NewKeyword.word_length); i++, j++)
{
    ... // program code
}

for (i = 0, j = 0;  
     (i < first_word_length) && (j < second_word_length);  
     i++, j++)
{
    ... // program code 
}
&sup1; 1-5：若函數或過程中的參數較長，則要進行適當的劃分。
示例：
n7stat_str_compare((BYTE *) & stat_object,
                   (BYTE *) & (act_task_table[taskno].stat_object),
                   sizeof (_STAT_OBJECT));

n7stat_flash_act_duration( stat_item, frame_id *STAT_TASK_CHECK_NUMBER
                                      + index, stat_object );
&sup1; 1-6：不允許把多個短語句寫在一行中，即一行只寫一條語句。
示例：如下例子不符合規范。
rect.length = 0;  rect.width = 0;

應如下書寫
rect.length = 0;
rect.width  = 0;
&sup1; 1-7：if、for、do、while、case、switch、default等語句自占一行，且if、for、do、while等語句的執行語句部分無論多少都要加括號{}。 
示例：如下例子不符合規范。
if (pUserCR == NULL) return;

應如下書寫：
if (pUserCR == NULL)
{
    return;
}
&sup1; 1-8：對齊只使用空格鍵，不使用TAB鍵。
說明：以免用不同的編輯器閱讀程序時，因TAB鍵所設置的空格數目不同而造成程序布局不整齊，不要使用BC作為編輯器合版本，因為BC會自動將8個空格變為一個TAB鍵，因此使用BC合入的版本大多會將縮進變亂。
&sup1; 1-9：函數或過程的開始、結構的定義及循環、判斷等語句中的代碼都要采用縮進風格，case語句下的情況處理語句也要遵從語句縮進要求。
&sup1; 1-10：程序塊的分界符（如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
}
&sup1; 1-11：在兩個以上的關鍵字、變量、常量進行對等操作時，它們之間的操作符之前、之后或者前后要加空格；進行非對等操作時，如果是關系密切的立即操作符（如－>），后不應加空格。
說明：采用這種松散方式編寫代碼的目的是使代碼更加清晰。
由于留空格所產生的清晰性是相對的，所以，在已經非常清晰的語句中沒有必要再留空格，如果語句已足夠清晰則括號內側(即左括號后面和右括號前面)不需要加空格，多重括號間不必加空格，因為在C/C++語言中括號已經是最清晰的標志了。
在長語句中，如果需要加的空格非常多，那么應該保持整體清晰，而在局部不加空格。給操作符留空格時不要連續留兩個以上空格。

示例：
(1) 逗號、分號只在后面加空格。
int a, b, c; 

(2)比較操作符, 賦值操作符"="、 "+="，算術操作符"+"、"%"，邏輯操作符"&&"、"&"，位域操作符"<<"、"^"等雙目操作符的前后加空格。
if (current_time >= MAX_TIME_VALUE) 
a = b + c;
a *= 2;
a = b ^ 2;

(3)"!"、"~"、"++"、"--"、"&"（地址運算符）等單目操作符前后不加空格。
*p = 'a';        // 內容操作"*"與內容之間
flag = !isEmpty; // 非操作"!"與內容之間
p = &mem;        // 地址操作"&" 與內容之間
i++;             // "++","--"與內容之間

(4)"->"、"."前后不加空格。
p->id = pid;     // "->"指針前后不加空格

(5) if、for、while、switch等與后面的括號間應加空格，使if等關鍵字更為突出、明顯。
if (a >= b && c > d)
&frac12; 1-1：一行程序以小于80字符為宜，不要寫得過長。
 
2 注釋
&sup1; 2-1：一般情況下，源程序有效注釋量必須在20％以上。
說明：注釋的原則是有助于對程序的閱讀理解，在該加的地方都加了，注釋不宜太多也不能太少，注釋語言必須準確、易懂、簡潔。
&sup1; 2-2：說明性文件（如頭文件.h文件、.inc文件、.def文件、編譯說明文件.cfg等）頭部應進行注釋，注釋必須列出：版權說明、版本號、生成日期、作者、內容、功能、與其它文件的關系、修改日志等，頭文件的注釋中還應有函數功能簡要說明。
示例：下面這段頭文件的頭注釋比較標準，當然，并不局限于此格式，但上述信息建議要包含在內。
/*************************************************
  Copyright (C), 1988-1999, Huawei Tech. Co., Ltd.
  File name:      // 文件名
  Author:       Version:        Date: // 作者、版本及完成日期
  Description:    // 用于詳細說明此程序文件完成的主要功能，與其他模塊
                  // 或函數的接口，輸出值、取值范圍、含義及參數間的控
                  // 制、順序、獨立或依賴等關系
  Others:         // 其它內容的說明
  Function List:  // 主要函數列表，每條記錄應包括函數名及功能簡要說明
    1. ....
  History:        // 修改歷史記錄列表，每條修改記錄應包括修改日期、修改
                  // 者及修改內容簡述  
    1. Date:
       Author:
       Modification:
    2. ...
*************************************************/
&sup1; 2-3：源文件頭部應進行注釋，列出：版權說明、版本號、生成日期、作者、模塊目的/功能、主要函數及其功能、修改日志等。
示例：下面這段源文件的頭注釋比較標準，當然，并不局限于此格式，但上述信息建議要包含在內。
/************************************************************