事先聲明一下，這篇文章是為完全沒有任何文檔編寫經(jīng)驗，并且正在使用Visual Studio的同學(xué)們準(zhǔn)備的，不一定適用于老鳥以及其他IDE愛好者 :-)

Ok, alpha版本的一個嚴(yán)重的問題便是，我們沒有任何的文檔積累;所以在Beta版本的開發(fā)中，PM準(zhǔn)備徹底消滅這種無文檔的編碼風(fēng)格。

既然要讓大家寫文檔，那么總該有個文檔規(guī)范吧!理論性的東西我就不多講了，這里我就講一個“南七規(guī)范”——簡單實用，不用費腦子。

南七規(guī)范 v1.0

不知道提到“文檔”，同學(xué)們首先會想到什么東西——不過我估計大概是這樣的風(fēng)格——工程里面有一個doc目錄，然后里面有各種不同開發(fā)人員維護(hù)的xxx.txt文件(或者微軟式xxx.doc);誠然，有很多工程的文檔組織形式就是這樣的，但是這樣做也有缺點，就是文檔可能一旦被寫出來就落后于代碼了——離代碼太遠(yuǎn)。還有一點就是分開維護(hù)的文檔可能覆蓋面太窄——代碼中會出現(xiàn)很多沒有在文檔中提到的方法。

所以在這里向大家介紹另外一種維護(hù)文檔的方法——注釋法(名字是我自己發(fā)明的，不要打我)。意思是說，程序員只需要在每個函數(shù)(或者類)開始之前加上一段特殊格式的注釋，然后就可以用專門的工具掃描整個代碼樹然后轉(zhuǎn)換成按照架構(gòu)組織好的(帶有多種目錄，甚至還可以搜索)html或pdf文檔。

這種方法的優(yōu)點在于，當(dāng)一個方法被重構(gòu)的時候，程序員可以輕而易舉地修改文檔，做到二者同步，而且如果保持每天都把文檔給Build出來的話，可讀性又很高。

我們的南七規(guī)范規(guī)定——必須給每個函數(shù)加上文檔，所以在每個函數(shù)前面，都必須寫一份注釋。

上個例子吧。

///<summary> 
    /// Initialize the resources, and starts a new game.  
    ///</summary> 
    ///<param name="songID">The ID of selected song.<remarks>The track selector should make sure  
    /// that this id is within [0..SongCount-1], otherwise the game will crash.</remarks></param> 
    ///<param name="level">The difficulty level, cound be 0(easy) or 1(hard)</param> 
 
    void StartGame(int songID,int level)  
    {  
        SoundGame.gps = new GamePlayScreen();  
        SoundGame.gps.Layer = 1;  
        GamePlayScreen.selectedSongID = songID;  
        GamePlayScreen.selectedSongLevel = level;  
        GamePlayScreen.startGameTime = TimeSpan.FromSeconds(-2);  
        ScreenManager.AddScreen(SoundGame.gps, null);  
        SoundGame.gps.InitializeGameLoop();  
    } 

注意代碼上面的那段注釋，特殊之處在于普通注釋都是兩道杠，這個文檔注釋是三道杠，盡顯尊貴。看到這里大家可能會說，麻煩!我告訴你，一點都不麻煩，只要你是在使用Visual Studio,那么你把光標(biāo)停在函數(shù)頭的前面，按一個三道杠——啪，自動補(bǔ)出來了，剩下的工作就是往里面填入內(nèi)容而已!

聰明的同學(xué)們可能已經(jīng)觀察出來了——三道杠里面套的不就是一些XML形式的結(jié)構(gòu)么?(再不明白的話，就像HTML一樣)于是就挨個填內(nèi)容吧——下面來幾個裸按三道杠補(bǔ)出來的樣板做示范——

///<summary> 
       ///   
       ///</summary> 
       ///<param name="position"></param> 
       ///<param name="tag"></param> 
       private void AddButton(Rectangle position,int tag)  
       {  
           TransparentButton tbutton = new TransparentButton(position,tag, this);  
           buttonList.Add(tbutton);  
       } 

這便是在任意一個函數(shù)前面按下三道杠之后自動補(bǔ)全的結(jié)果。可以看到整個XML結(jié)構(gòu)分為兩個部分，一個叫summary，另一個是一堆param。

summary部分是對這個函數(shù)的作用，行為的描述，我的建議是，這里的描述要像說明書一樣——你在寫注釋的時候就要假設(shè)有個十萬個為什么正在問你，這個函數(shù)應(yīng)該怎么用，輸入什么，吐出來什么，副作用是什么——但是不要牽扯到太多內(nèi)部實現(xiàn)的細(xì)節(jié)——什么把XXX對象加入到_YYY隊列中——這明顯不是說明書應(yīng)該做的事情，要想弄清楚這些事情，最好的方式是讀代碼(相信我，這種情況下看代碼比看注釋清楚又高效)

于是我們?yōu)锳ddButton函數(shù)填入如下文檔：

///<summary> 
       /// Register a button to the system, so that it will be displayed and handled on the game screen.  
       ///</summary> 
       ///<param name="position">The position description rectangle of the button.</param> 
       ///<param name="tag">The global-unique ID of the button.</param> 
       private void AddButton(Rectangle position,int tag)  
       {  
           TransparentButton tbutton = new TransparentButton(position,tag, this);  
           buttonList.Add(tbutton);  
       } 

接下來再來看一份糟糕一點的文檔：

///<summary> 
      /// Add a TransparentButton to the buttonList  
      ///</summary> 
      ///<param name="position">Position.</param> 
      ///<param name="tag">The tag of the button.</param> 
      private void AddButton(Rectangle position,int tag)  
      {  
          TransparentButton tbutton = new TransparentButton(position,tag, this);  
          buttonList.Add(tbutton);  
      } 

為什么說它糟糕?第一，它有很多內(nèi)部實現(xiàn)，現(xiàn)在看著代碼可能感覺不出來，但是當(dāng)這份文檔最終編譯成pdf之后就能體會到這種痛苦了——文檔閱讀者根本不明白你在說什么(否則為什么他不直接去看代碼呢?)第二，定義不清晰——用Position解釋Position是廢話;"The tag of the button"最終沒有解釋Tag是個什么玩意。

希望這樣介紹一下能讓同學(xué)們明白好的文檔和差的文檔有什么區(qū)別。 :-)

另外補(bǔ)充一點，XML結(jié)構(gòu)的文檔實際上是可以嵌套的，例如你可以在summary里面嵌套code

///<summary> 
///請看代碼  
///<code> 
/// 床前明月光();  
/// 疑是地上霜();  
/// 舉頭望明月();  
/// 低頭思故鄉(xiāng)();  
///<code/> 
///</summary> 

等等，具體你在三道杠內(nèi)部打一個<然后能夠用的東西就會被補(bǔ)全出來了。注意這里嵌套的結(jié)構(gòu)實際上的作用是對格式進(jìn)行指定，例如段會用等寬字體，等等。

原文：http://www.cnblogs.com/southseven/archive/2011/11/07/2239555.html

Ok,ok finally假設(shè)大家都這樣去寫碼了，接下來怎么辦?這里簡單提一下一個叫doxygen的開源工具。doxygen正是前文提到的那個能自動掃描代碼樹并且生成html或者latex(于是就可以編譯成pdf)文檔的工具，這個工具太出名了，以至于隨便放狗一搜就能得到其使用方法，這里我就不多講了。 :-) 總之就這樣幾個步驟——1. doxygen -g得到一個配置文件樣本 2.稍微修改一下，例如是否遞歸找文件 3.doxygen doxyFile 4.驗收你的漂亮的文檔網(wǎng)頁或者PDF。