華為標準註釋與文件，以及程式碼規範
註釋
為什麼要寫註釋呢？為什麼要寫文件呢?
也許有人會這樣問。但是我只想說如果你還在這樣問，那麼你不僅不是一個優秀的程式設計師，應該說你是不是程式設計師都應該受到質疑。
先說一下注釋的重要性：
在公司的開發中，我們要明白程式不是寫給自己看的，也不是所有的程式碼都是自己寫的，我們不僅需要看別人的程式碼而且還要把自己的程式碼交給別人看，團隊看。也許還會在你離職以後交給你的接班人看。而且，就算是你寫的程式，如果過了很久你再去看的話（相信也會受到一萬點真實傷害，脫口而出”這是哪個傢伙寫的這是什麼東西！！！”）所以，程式文件的書寫，註釋的書寫，以及標準的編碼規範就非常的重要。（而這些是每一個大學老師都不會交給你的）
-
一般情況下，源程式的有效註釋量必須在20%以上。
說明：註釋的原則是有助於對程式的閱讀理解，在該加的地方都加上，註釋不宜太多。也不能太少。註釋語言必須準確、易懂、簡潔 -
說明性檔案（如標頭檔案.h檔案、inc檔案、.def檔案、編譯說明檔案.cfg等）頭部應該進行註釋，註釋必須列出：版本說明、版本號、生成日期、作者、內容、功能、與其它檔案的關係、修改日誌等，標頭檔案的註釋還應有函式功能簡要說明
示例(本人的標頭檔案頭註釋，當然並不侷限此格式)： -
原始檔頭部應進行註釋，列出：版權說明、版本號、生成日期、作者、模組目的/功能、主要函式及其功能、修改日誌等。
示例（本人原始檔頭註釋，不侷限與此格式）
說明：Description一項描述本檔案的內容、功能、內容各部分之間的關係及本檔案與其他檔案關係等。History是修改歷史列表，每條記錄應包括修改日期、修改人、修改內容簡述等。 -
函式頭部進行註釋，例出：函式的目的/功能、輸入引數、輸出引數、返回值、呼叫關係（函式、表）等。
示例：（本人的函式頭註釋，不侷限與此格式） -
我們應該養成邊寫程式碼邊註釋的習慣，修改程式碼同時修改相應的註釋，以保證註釋與程式碼的一致性。不再有用的註釋要刪除
- 註釋內容要清楚、明瞭、含義準確、防止註釋二義性。
說明：錯誤的註釋不但無益反而有害 - 避免在程式碼中使用縮寫，特別是非常用的縮寫
說明：在使用縮寫時或之前，應對縮寫進行必要的說明。 - 註釋應與其描述的程式碼相近，對程式碼的註釋應放在上方（對程式碼塊的註釋）或右方（對單條語句的註釋），相鄰位置，不可放在下面，如放在上方則需要與其上面的程式碼用空行隔開
例如：
//塊註釋
/* get replicate sub system index and net indicator */
repss_ind = ssn_data[index].repssn_index;
repss_ni = ssn_data[index].ni;
//單句註釋
int num = MAXSIZE; //set num = MAX- 對於所有有物理含義的變數、常量，如果其命名不是充分自注釋的，在宣告時必須加以註釋，說明其物理含義。變數、常量、巨集的註釋應該放在其上方或右方
示例：
/* active statistic task number */
#define MAX_ACT_TASK_NUMBER 1000- 資料結構宣告（包括陣列、結構、類、列舉等），如果其命名不是充分自注釋的，必須加以註釋。對資料結構的註釋應該放在其上方相鄰位置，不可放在下面，對結構的每個域的註釋要放在此域的右方
示例：
/* sccp interface with sccp user primitive message name */
enum SCCP_USER_PRIMITIVE
{
N_UNITDATA_IND，/* sccp notify sccp user uint data */
N_NOTTICE_IND， /* sccp notify user the NO.7 net */
/* transmission this message */
N_UNITDATA_ERQ /* sccp user's unit data transmission */
};- 全域性變數要有詳細的註釋，抱括對其功能、取值範圍、哪些函式或過程存取它以及存取時注意事項等等
示例：
/* The ErrorCode when SCCP translate */
/* Global Title failure, as follows */
/* 0 -- SUCCESS 1 -- GT Table error */
/* 2 -- GT error others - no user */
/* only function SCCPTranslate() in */
/* this modual can modlify it, and other */
/* modual can visit it through call */
/* the function GetGTTransErrorCode() */
BYTE g_GTranErrorCode;
- 註釋與所描述的內容進行同樣的縮排,並且將註釋與其上面的程式碼用空行分隔
說明：可使程式排版整齊，並方便註釋的閱讀與理解
示例：
void example_fun(void)
{
/* Code one comments */
CodeBlock One;
/* Code two comments */
CodeBlock Two;
}- 對變數的定義和分支語句（條件分支、迴圈語句等）必須編寫註釋
說明：這些語句往往是程式實現某一特定功能的關鍵，對於維護人員來說，良好的註釋幫助更好的理解程式，有時甚至優於看設計文件 - 對於switch語句下的case語句，如果因為特殊情況需要處理完一個case後進入下一個case處理，必須在該case語句處理完後，下一個語句前加上明確的註釋。
說明：這樣比較清楚程式編寫者的意圖，有效防止無故遺漏break語句
示例
switch(elect)
{
num CMB_UP:
{
pressup();
break;
}
case CMB_DOWN:
{
num = pressdown();
if (num > 1)
{
break;
}
else
{
/* not break */
/* now must jump to CMB_MIND */
}
}
case CMB_MIND:
{
...
break;
}
}- 除非必要，請不要在一行程式碼的中間插入註釋，否則會讓程式的可讀性降低
- 通過對函式或過程、變數、結構等正確的命名以合理的組織程式碼的結構，使程式碼成為自注釋的
- 在程式碼的功能、意圖層次上進行註釋，提供有用的，額外的資訊
說明：註釋的目的是解釋程式碼的目的，功能和採用的方法，提供程式碼以外的資訊，幫助讀者理解程式碼，防止沒有必要的重複註釋資訊。
示例：
//該註釋提供了有用的資訊
/* if mtp receive a message from links */
if (receive_flag)- 在程式碼塊的結束行右方加註釋標記，以表明某程式塊結束
說明：當代碼段較長，特別是多重巢狀時，這樣做可以使程式碼更清晰，更便於閱讀
示例：
if (...)
{
//progream code
while (index < MAX_INDEX)
{
//progream code;
}/*while end */
}/*end of if*/ //指明是哪條if結束- 註釋格式儘量統一，建議使用 /* …… */
- 註釋應考慮程式易讀及外觀排版的因素，使用的語言若是中、英兼有的，建議多使用中文，除非能夠用非常流利準確的英文表達
說明：註釋語言不統一，影響程式易讀性和外觀排版，出於對維護人員的考慮，建議使用中文
程式碼規範
程式碼規範這一點就不用多說了，寫程式一定要有規範，否則你會被別人說你的程式像狗屎一樣難看。而且讀起來簡直頭疼到爆炸。這裡我就小小的展示一下我的程式碼規範，一般大家都有自己的習慣，也應該養成這樣的好習慣。這樣不僅會為你的面試工作加分，而且可以提高你的開發效率。
以上的程式碼格式是博主自己養成的編碼習慣，還算是標準，僅供大家參考，每個人都有每個人的習慣，但是有習慣總比沒有習慣隨便寫的好！！！
本文來自 zxnsirius 的CSDN 部落格 ，全文地址請點選：https://blog.csdn.net/zxnsirius/article/details/51138793