日韩无码专区无码一级三级片|91人人爱网站中日韩无码电影|厨房大战丰满熟妇|AV高清无码在线免费观看|另类AV日韩少妇熟女|中文日本大黄一级黄色片|色情在线视频免费|亚洲成人特黄a片|黄片wwwav色图欧美|欧亚乱色一区二区三区

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

十多年的順慶網(wǎng)站建設(shè)經(jīng)驗(yàn)，針對(duì)設(shè)計(jì)、前端、開(kāi)發(fā)、售后、文案、推廣等六對(duì)一服務(wù)，響應(yīng)快，48小時(shí)及時(shí)工作處理。全網(wǎng)營(yíng)銷推廣的優(yōu)勢(shì)是能夠根據(jù)用戶設(shè)備顯示端的尺寸不同，自動(dòng)調(diào)整順慶建站的顯示方式，使網(wǎng)站能夠適用不同顯示終端，在瀏覽器中調(diào)整網(wǎng)站的寬度，無(wú)論在任何一種瀏覽器上瀏覽網(wǎng)站，都能展現(xiàn)優(yōu)雅布局與設(shè)計(jì)，從而大程度地提升瀏覽體驗(yàn)。成都創(chuàng)新互聯(lián)公司從事“順慶網(wǎng)站設(shè)計(jì)”,“順慶網(wǎng)站推廣”以來(lái)，每個(gè)客戶項(xiàng)目都認(rèn)真落實(shí)執(zhí)行。

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

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

南七規(guī)范 v1.0

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

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

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

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

上個(gè)例子吧。

 
 

  
  
///

  
  
    /// Initialize the resources, and starts a new game. 
  
  
    ///
  
  
    ///The ID of selected song.The track selector should make sure 
  
  
    /// that this id is within [0..SongCount-1], otherwise the game will crash.
  
  
    ///The difficulty level, cound be 0(easy) or 1(hard)
  
  

  
  
    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(); 
  
  
    }
 
 

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

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

 
 

  
  
///

  
  
       ///  
  
  
       ///
  
  
       ///
  
  
       ///
  
  
       private void AddButton(Rectangle position,int tag) 
  
  
       { 
  
  
           TransparentButton tbutton = new TransparentButton(position,tag, this); 
  
  
           buttonList.Add(tbutton); 
  
  
       }
 
 

這便是在任意一個(gè)函數(shù)前面按下三道杠之后自動(dòng)補(bǔ)全的結(jié)果?？梢钥吹秸麄€(gè)XML結(jié)構(gòu)分為兩個(gè)部分，一個(gè)叫summary，另一個(gè)是一堆param。

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

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

 
 

  
  
///

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

接下來(lái)再來(lái)看一份糟糕一點(diǎn)的文檔：

 
 

  
  
///

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

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

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

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

 
 

  
  
///

  
  
///請(qǐng)看代碼 
  
  
///

  
  
/// 床前明月光(); 
  
  
/// 疑是地上霜(); 
  
  
/// 舉頭望明月(); 
  
  
/// 低頭思故鄉(xiāng)(); 
  
  
///

  
  
///
 
 

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

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

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