暮鼓集    行走集

原作於2008年06月01日，軟體部培訓稿

我們修改程式碼時少不了要加一些註釋，這基本的原則是“言簡意賅”，只要做到大家能看懂，在版本比較工具(BC及VSS)中能一目瞭然，這就可以了。

下面介紹一些方法供大家參考：

為某一專案或者某一MACRO配置而新增的程式碼

#if defined(__PROJECT_A__) // Add by XXX, YYYY-MM-DD
...Your codes
#elif defined(__PROJECT_B__) // Add by YYY, YYYY-MM-DD
...Other codes
#else
...Orginal codes
#endif  
 

為修改某一Bug而新增並通用於各專案的程式碼

#if 1 // Add by XXX, YYYY-MM-DD
...Your codes
#else
...Original codes
#endif  

如果需要說明是為了什麼而修改，也可將註釋單列一行。

// Add by XXX, YYYY-MM-DD
// ... Description
// ...

每行的長度不要太長，建議為80個字元，按照公司規定的流程，如果是修改Bug管理系統中的問題，必須註明Bug單的編號。

  // Add by XXX, YYYY-MM-DD, Bug No.QSXXXXXX

部分RD習慣這樣寫：

// Add by XXX
// End XXX  

在絕大多數情況下，這沒有問題，我的方法稍做改變，與之前所說的類似

#if 1 // Add by XXX, YYYY-MM-DD
...Your codes
#endif

這樣寫的好處是－在除錯時可方便地將改寫的程式碼關閉看原來MTK的效果，而不必去Mark掉。如果只增加了單行程式碼，並且無須解釋就可以明其意，也可以這樣寫

...Your code // Add by XXX, YYYY-MM-DD  

如果習慣使用//Add //End的風格，請注意如下情況

// Add by XXX
#if defined(__PROJECT_A__)
...
#elif deined(__PROJECT_B__)
//End by XXX
#else
...
..
// Add by XXX
#endif
// End XXX  
 

最後這個#endif前後所加註釋為多餘，有經驗的RD看了上半部分便知哪裡是改過的，即使有問題，用版本工具一比較即可。

加了太多的// Add, //End會讓程式碼看起來繁冗不堪，反而影響閱讀。

還有一種情況，在一個函式中修改了很多地方

void func( void )
{
//Add by XXX
...
// End XXX
...
//Add by XXX
...
// End XXX
...
//Add by XXX
...
// End XXX
}

我建議，當一個函式中修改的部分超過1/3時，不如將此函式分開

#if 1 // Add by XXX, YYYY-MM-DD
void func( void )
{...}
#else // Orginal code
void func( void )
{...}
#endif