運籌帷幄之中決勝千裡之外 菜鳥初識代碼編程規範一 注釋規範

       良好的注釋規範可以為團隊合作開發推波助瀾，無論在項目開發，還是產品維護上都起到了至關重要的作用。應該說注釋規範是一種約定，也是程式員之間良好溝通的橋樑。

   我們從現在就應該養成良好的編程規範，嚴格要求自己，米老師常說“要想成為高端人才，就對自己的要求高一點”。加油！

注釋規範：

             

a)  注釋中，應標明對象的完整的名稱及其用途，但應避免對代碼過於詳細的描述。

b)  每行注釋的最大長度為100個字元。

c)  將注釋與注釋分隔字元用一個空格分開。

d)  不允許給注釋加外框。

e)  編碼的同時書寫注釋。

f)  重要變數必須有注釋。

g)   變數注釋和變數在同一行，所有注釋必須對齊，與變數分開至少兩個“Tab”鍵。

如：

int  iLevel, iCount;     // iLevel ....tree level                                       // iCount ....count of tree items      string strSql;            //SQL

h)  典型演算法必須有注釋。

i)  在迴圈和邏輯分支地方的上行必須就近書寫注釋。

j)   程式段或語句的注釋在程式段或語句的上一行.

k)  在代碼交付之前，必須刪掉臨時的或無關的注釋。

l)   為便於閱讀代碼，每行代碼的長度應少於100個字元。

 

對於自己建立的代碼檔案（如函數、指令碼），在檔案開頭，一般編寫如下注釋：

/******************************************************    FileName:Copyright  (c)  2010-xxxxWriter: 某某某Create Date:Rewriter:Rewrite Date:Impact:Main Content（Function Name、parameters、returns）                  ******************************************************/

 

 

模組開始必須以以下形式書寫模組注釋：

///<summary>///Module ID：<模組編號，可以引用系統設計中的模組編號>///Depiction：<對此類的描述，可以引用系統設計中的描述>///Author：作者中文名///Create Date：<模組建立日期，格式：YYYY-MM-DD>///</summary>

 

 

如果模組只進行部分少量代碼的修改時，則每次修改須添加以下注釋：

///Rewriter：Rewrite Date：<修改日期，格式：YYYY-MM-DD>  Start1：         /* 原代碼內容*////End1：                                將原代碼內容注釋掉，然後添加新代碼使用以下注釋：///Added by： Add date：<添加日期，格式：YYYY-MM-DD>   Start2：        新代碼內容///End2：                     

           

 

 

如果模組輸入輸出參數或功能結構有較大修改，則每次修改必須添加以下注釋：

///<summary>///Log ID：<Log編號,從1開始一次增加>///depiction：<對此修改的描述>///Writer：修改者中文名///Rewrite Date：<模組修改日期，格式：YYYY-MM-DD>///</summary>

   

 

 

在類的屬性必須以以下格式編寫屬性注釋：

///<summary>/// <Properties depiction>/// </summary>

在類的方法聲明前必須以以下格式編寫注釋

     

   ///<summary>        ///depiction：<對該方法的說明>        ///</summary>        ///<param name="<參數名稱>"><參數說明></param>             ///<returns>             ///<對方法傳回值的說明，該說明必須明確說明返回的值代表什麼含義>      ///</returns>        ///Writer：作者中文名        ///Create Date：<方法建立日期，格式：YYYY-MM-DD>

       

 

代碼間注釋分為單行注釋和多行注釋：

    單行注釋：

//<單行注釋>     多行注釋：     /*多行注釋1     多行注釋2     多行注釋3*/

代碼中遇到語句塊時必須添加註釋（if,for,foreach,……）,添加的注釋必須能夠說明此語句塊的作用和實現手段（所用演算法等等）。

 

1. Comment each level（每個層級的注釋有統一的風格）

注釋每一個代碼塊，並且在各個層級的代碼塊上，要使用統一的注釋方法。例如：

對於類，應包含簡單的描述、作者以及最近的更改日期
對於方法，應包含目的的描述、功能、參數以及傳回值

使用統一的注釋規則對於一個團隊是非常重要的。當然，更加推薦使用注釋的約定和工具（例如，C#的XML或Java的Javadoc），它們會是注釋變得更加容易。

2. Use paragraph comments（對段落注釋）

將代碼塊分成若干完成獨立功能的"段落"，並在每個"段落"前添加註釋，向讀者說明"即將發生什麼"。

// Check that all data records// are correct foreach (Record record in records) {if (rec.checkStatus()==Status.OK){ . . . } } // Now we begin to perform // transactions Context ctx = new ApplicationContext(); ctx.BeginTransaction();. . .

3. Align comments in consecutive lines（對齊注釋行）

對於擁有尾碼式注釋的多行代碼，排版注釋代碼，使各行注釋對齊到同一列。

const MAX_ITEMS = 10; // maximum number of packets const MASK = 0x1F; // mask bit TCP 

一些開發人員使用tab來對齊注釋，有些則使用空格。但是由於tab在不同的編輯器或者IDE上會有所不同，最好還是使用空格。

4. Don't insult the reader's intelligence（不要侮辱讀者的智商）

不要寫沒用的注釋，例如：

if (a == 5) // if a equals 5 counter = 0; // set the counter to zero

寫這種無用的注釋不但浪費你的時間，而且讀者在讀這種很容易理解的代碼時，很容易被你的注釋轉移注意力，浪費了時間。

5. Be polite（要有禮貌）

不要寫不禮貌的注釋代碼，例如"注意，愚蠢的使用者輸入了一個負數"，或者"修正由於最初的開發人員的可憐且愚蠢的編碼所造成的副作用"。這樣的注釋冒犯了作者，而且你並不知道誰會在將來讀到這段注釋--你老闆、客戶或者是你在注釋中冒犯的那個可憐且愚蠢的開發人員。

6. Get to the point（簡明扼要）

不要在注釋中寫的過多，不要寫玩笑、詩和冗長的話。總之，注釋需要簡單直接。

7. Use a consistent style（風格一致）

一些人認為注釋應該能讓非程式員也能看懂，但是也有些人認為注釋僅僅是指導程式員的。不管怎麼說，像《Successful Strategies for Commenting Code》中所說，真正重要的是注釋始終面向同一個讀者，在這點上，應該保持一致。個人認為，我很懷疑會有非程式人員閱讀代碼，所以應該把閱讀注釋的對象定位為開發人員。

8. Use special tags for internal use（在內部使用特殊的標籤）

團隊中處理代碼時，在程式員之間應採用一系列統一的‘標籤注釋'進行交流。例如，很多團隊使用"TODO"來表示一段需要額外工作的代碼。

int Estimate(int x, int y) {// TODO: implement the calculations return 0;}

‘標籤注釋'並不解釋代碼，而是引起主意或者傳遞資訊。但是，使用這種方法時，務必要完成‘標籤注釋'傳遞的資訊。

9. Comment code while writing it（寫代碼的同時，完成注釋）

寫代碼的同時添加註釋，因為此時你的思路最為清晰。如果你把注釋的任務留到最後，那麼你相當於經曆了兩次編碼。"我沒有時間注釋""我太忙了""項目耽誤了"這些往往是不寫注釋的理由。所以，程式員們認為，最理想的解決方案是‘寫代碼前先寫注釋'。例如：

public void ProcessOrder() {// Make sure the products are available// Check that the customer is valid // Send the order to the store // Generate bill }

10. Write comments as if they were for you (in fact, they are)把代碼的讀者想象成你自己（實際情況往往如此）

注釋代碼時，不僅僅要為將來可能維護你代碼的人考慮，而且要考慮到讀注釋的可能是你。偉大的Phil Haack說過："每當有一行代碼被敲上螢幕，你都要從維護的角度審視一遍這段代碼。" "As soon as a line of code is laid on the screen, you're in maintenance mode on that piece of code."（著名的話不敢不附上原句）

結果，我們自己往往是我們良好注釋的受益者，或者是爛注釋的受害人。

11. Update comments when you update the code（更新代碼時，記得更新注釋）

如果不能隨著代碼的更新而更新注釋，那麼即使再準確的注釋也毫無意義。代碼和注釋必須同步，否則這些注釋對於維護你代碼的程式人員來說簡直是折磨。在使用refactoring工具自動更新代碼時，應尤其注意，它們會自動更新代碼而不會改變注釋，這些注釋自然就到期了。

 

12. The golden rule of comments: readable code（可讀性良好的代碼是最好的注釋）

對於許多程式員來說，基本的原則之一就是：讓代碼自己說話。有人可能會懷疑這是那些不愛寫注釋的程式員的借口，然而這確實是一個不爭的事實。自我解釋良好的代碼對於編碼來說大有益處，不但代碼容易理解甚至使注釋變得沒有必要。舉例來說，在我的文章《Fluid Interfaces》中展示了什麼是清晰的自我解釋型代碼：

Calculator calc = new Calculator();calc.Set(0);calc.Add(10);calc.Multiply(2);calc.Subtract(4);Console.WriteLine( "Result: {0}", calc.Get() );

在本例中，注釋是沒必要的，並且會違背tip#4 。為了使代碼更加可讀，應該考慮使用適當的名字（像在經典的《Ottinger's Rules》描述的），確保正確的縮排和代碼風格欄線（代碼風格欄線是類似於#region #endregion這類的東西吧？）。如果這一點做的不好，直接後果是，你的注釋看起來就像是在為晦澀難懂的代碼而道歉。

13. Share these tips with your colleagues（與你的同事share這些tips）

儘管tip#10中曾說過良好的注釋會是自己從中收益，但是這些tips會使所有開發人員收益，尤其是在團隊合作的環境中。因此大方的與同事分享這些注釋的技巧，讓我們都能寫出易懂而且好維護的代碼。