heeeey

本文來自CSDN博客，轉(zhuǎn)載請標明出處：http://blog.csdn.net/smartduck/archive/2005/08/25/464720.aspx

一.問題
  1.工程太龐大了:代碼行總數(shù):1038099(88.24%);
  2.注釋太少了:注釋行總數(shù):92759(7.88%);
  3.新員工上手教慢;
  4.維護時發(fā)現(xiàn)有些代碼作者都看不懂了;
二.思路
  1.增加注釋
  2.統(tǒng)一注釋格式
  3.抽取注釋, 生成文檔, 提供給新員工
三.實現(xiàn)
  1. 采用doxygen注釋.
  2.每個.h文件的頭部,必須添加注釋,格式如下:
  /** \file file.h
   * A brief file description.
   * A more elaborated file description.
   */

  3.每個類的聲明上方,必須添加注釋,格式如下:
  /** \class Test class.h
   *  \brief This is a test class.
   *
   * Some details about the Test class
   */
   class Test
   {
    ...
   };

  4.每個成員變量及成員函數(shù)的定義的右邊或上方,必須添加注釋,格式如下:
  /** Some details about the function open */
  void open();

  5.每個全局函數(shù)、全局變量、宏定義的定義的右邊或上方,必須添加注釋,格式如下:
  /** Some details about the function GlobalFunc*/
  void GlobalFunc();

  6.每個.cpp文件頭部,必須添加注釋,格式如下:
  /** \file file.cpp
   * A brief file description.
   * A more elaborated file description.
   */

   7.每個函數(shù)的實現(xiàn)上方,必須添加注釋,格式如下:
  /** \brief A member function.
   *  \param c a character.
   *  \param n an integer.
   *  \exception std::out_of_range parameter is out of range.
   *  \return a character pointer.
   */
   const char *member(char,int) throw(std::out_of_range)
   {
   }

   8.每個枚舉定義必須添加注釋,格式如下:
      /** Another enum, with inline docs */
      enum AnotherEnum
      {
        V1, //< value 1
        V2  //< value 2
      };

  9.實現(xiàn)代碼中關(guān)鍵的代碼必須加注釋,格式如下:
  {
    //some details about the next line code
    if (Button1->Enabled)
    {
    }
  }
 
  10. 必須實行代碼檢查機制.

注:
什么是doxygen呢？下面的介紹錄自doxygen的網(wǎng)頁：
“doxygen是一種用于C++、IDL（Corba、Microsoft和KDE-2 DCOP風格）和C的文檔系統(tǒng)。它可以通過三種方式來幫助你：
1. 它可以從一組標有文檔的源文件中生成在線文檔瀏覽器（HTML格式），以及/或者離線參考手冊（LATEX格式）。同時還支持生成RTF（MS-Word）、Postscript、超鏈接PDF、壓縮HTML和UNIX man頁面格式的輸出。文檔是從源文件中直接提取的，從而十分容易保持文檔和源碼的一致。
2. 可配置doxygen，用以從沒有標注文檔的源文件中提取代碼結(jié)構(gòu)。這對于要在大量源文件中快速地找到所需的東西來說是非常有用的。通過include依賴圖、繼承圖和協(xié)作圖等手段（它們都是自動生成的），可以使不同成分之間的關(guān)系可視化。
3. 你甚至還可以“濫用”doxygen，創(chuàng)建普通文檔。”