C++編碼規範(1):代碼注釋

文章目錄

• 6.TODO 注釋

C++編碼規範(1):代碼注釋

C++編碼規範(2):命名規範

 

當你閱讀別人的代碼時如果沒有注釋那會是件比較痛苦的事.一說到注釋我們馬上想到是通過//或/* */這樣來添加一些描述資訊.這隻是狹義的注釋.

廣義的注釋我們可以理解為,任何有助於理解代碼的資訊都可以看成注釋.

我們可以把寫代碼和寫文章類比下.自然語言會有詞法,句法,語義這幾個概念.代碼中的文法和句法就相當於一個程式設計語言中的基本文法規範.這是我們學習一門程式設計語言必須掌握的.所以注釋的時候一般不會涉及到這些資訊.

注釋主要涉及到語義的描述.語義從大的方向,軟體產品面向的應用來說,就是要解決的問題本身的邏輯,如果是些應用軟體也可以叫商務邏輯.我們把商務邏輯理清頭緒後就會來個啥資料建模之類的.然後寫設計文檔之類的,有啥概要設計與詳細設計,這些文檔可以看成非常重要的注釋.

然後就是寫到代碼裡的注釋了,通過//或/* */標識出來.還有一種注釋叫自我注釋,就是通過函數或變數名字就得得到一些有用的資訊

 

這裡主要講下用//或/* */做的注釋

用// 還是/* */就看你自己的偏好了.最重要的是保持一致,就是在一個項目中大家達成一致,全部用哪一種或者在某個地方用//,另外的地方用/* */

 

注釋的位置及常見內容

 

1.檔案注釋

在C++的代碼都是分布在一個個的標頭檔和源檔案中,如果是用的VS則是h尾碼檔案和cpp尾碼檔案. 當然了有時你用以內嵌函式還可能會有inl檔案.每個檔案的開頭部分你可以添加註釋資訊.

內容一般是:著作權,作者,編寫日期,功能描述.例如

/**************************************************************************

Copyright:MyCompany

Author: Arwen

Date:2013-01-09

Description:Provide  functions  to connect Oracle

**************************************************************************/

或者

//Copyright:MyCompany

//Author: Arwen

//Date:2013-01-09

//Description:Provide functions to connect Oracle

 

有時如果修改了代碼,還可以添加修改人,日期,修改內容有目的這些資訊.

 

2.類注釋

一般是簡單的說下這個類的功能,如果你在檔案開頭已經描述了這裡也可以省略.如果要注釋的話就可以這樣簡單的描述下.

// COleDataObject -- simple wrapper for IDataObject

class COleDataObject
{

}

或者

/*COleDataObject -- simple wrapper for IDataObject*/

 

3.函數注釋

描述函數的功能及參數,其他相關資訊.例如

//Summary:  connect the database

//Parameters:

//       connInfo:A class contains the connect info ,such as user name ,pwd,etc.

//       directConnect : use TNS name or use direct connection info

//Return : true is connect successfully.

bool ConnectDatabase(ConnectInfo connInfo, bool directConnect);

 

或者

/*

*Summary: connect the database

*Parameters:

*     connInfo:A class contains the connect info ,such as user name ,pwd,etc.*    

*     directConnect : use TNS name or use direct connection info

*Return : true is connect successfully.

*/

 

 

4.變數注釋

一個變數如果代表的意思不容易從變數名看出來,而且又挺重要的話最好也加點注釋.例如

UINT m_nGrowBy;     // number of cache elements to grow by for new allocs

或者

UINT m_nGrowBy;     /* number of cache elements to grow by for new allocs*/

 

5.實現注釋

在一些邏輯性很強,不容易理解的代碼塊前添加註釋.特別是是像一些演算法,看起來就幾行,但想個半天都未必明白到底是啥意思來著.

例如

// copy elements into the empty space
 while (nCount--)
      m_pData[nIndex++] = newElement;

還有就是如果想針對函數的某些個參數做些注釋,那最好把參數分幾行寫.

void MyFunction(string name, //This is my name

                         int age)

 

另外有時一個函數很長,裡面有奶多個大括弧{ } ,這樣一嵌套,有時你不知道誰對應誰了,你要往裡面插入代碼就容易出錯.你也可以在些結尾的大括弧加個注釋,表明它是哪個if或while語句的結束處.

在C#中是可以通過#region 加 #endregion 來做注釋.同時開發環境VS能提供支援讓你方便的摺疊這樣注釋的代碼.

VS也支援在C++中通過#pragma region 與 #pragma endregion
來做注釋,但這在其它編譯器中不會被識別,所以需要考慮到跨平台的話或者會使用不同的編譯器的話就最好別用.

 

6.TODO 注釋

todo的意思就是待做的事.比如你代碼寫了一半,然後下班了.為了方便你第二天很快的找到那具體地方,或者防止你忘記.就可以用todo注釋下.因為一些開發環境提供了對它的支援,可以讓你方便的找到哪些個地方有todo注釋,起個書籤的作用.你選View-->Task List,然後在下面的下拉式清單中選擇comments就會列出所有TODO注釋資訊.

另外你也可以寫個TODO留著以後實現那功能也行,注釋資訊一般可以寫上你的名字和郵箱,然後說下待實現的功能或其他事項