1.4.6　正確書寫注釋

雖然在編譯時注釋會被編譯器忽略，但注釋對代碼的可讀性具有極其重要的作用。代碼如果沒有注釋或者注釋很少，那么不僅其他人不容易看懂，即使是代碼的作者，一段時間之后再次接觸也會一頭霧水。但代碼中的注釋要恰到好處，不宜過多或者畫蛇添足。畢竟，如果一段代碼的功能是清晰的，變量的命名符合習慣，則代碼本身就可以說明其運行邏輯，而不必進行過多的注釋。因此，我們更多看到的注釋，通常存在于針對接口的說明中，比如函數的功能描述、各個參數的含義、有關返回值的說明、結構體中每個成員的含義等。

關于C代碼中注釋的書寫，建議如下。

（1）為對外的接口提供詳細的注釋，并采用Doxygen（或其他文檔生成工具，如GtkDoc）允許的格式來撰寫注釋。對于函數，應就其功能、參數以及返回值做詳細說明；對于結構體，應就其公開的成員做詳細說明。現在，越來越多的開源項目采用Doxygen允許的格式，以隨同代碼共存的注釋形式來編寫和維護接口的說明文檔。這既方便開發者閱讀，又便于維護，尤其在接口發生變化時，開發者可以在修改代碼的同時完成對文檔的修改。在本章的后面，讀者可以看到采用Doxygen允許的格式撰寫的接口注釋。

（2）在不對外的內部模塊中，應就文件的功能、內部函數的用途等做簡要的注釋。除非代碼涉及復雜或重要的算法，否則不必過多地撰寫注釋。這是因為，當我們使用了合乎習慣的命名方法，并掌握了常見的接口設計模式之后，看接口及其實現就能知悉代碼邏輯；此種情況下，額外地撰寫注釋就是畫蛇添足。

（3）避免使用C++的注釋形式。C++的注釋形式（即“//”形式）輸入方便，具有一些優點。但是如前所述，代碼最重要的特質就是風格統一，因此在C代碼中還是應該統一采用傳統的注釋風格。在Linux內核以及大多數重要的C語言程序中，我們很少看到C++風格的注釋。一個好的習慣是僅在行尾的簡短注釋中使用C++風格的注釋。

（4）巧用XXX、FIXME、TODO等短語。XXX具有告誡意味，表示這段代碼非常重要，必須認真閱讀。FIXME一般表示這段代碼不夠完善，存在提高空間。TODO一般表示這段代碼的功能還不完整，有待未來完成。有些智能的代碼編輯器會將注釋中的這些特殊短語用特殊的顏色加以顯示，以提醒代碼的閱讀者。

（5）學習Linux內核編碼風格提倡的注釋編寫風格（見本章前面的內容），而不要添加額外的裝飾用字符。

下面的代碼片段定義的枚舉類型用于區別不同的變體類型，其中兩次使用了XXX標記，用于特別提醒開發者。在現代編輯器中查看這段代碼，XXX會顯示為醒目的紅色。

typedef enum purc_variant_type {
    PURC_VARIANT_TYPE_FIRST = 0,
　
    /* XXX: keep consistency with type names */
#define PURC_VARIANT_TYPE_NAME_UNDEFINED    "undefined"
    PURC_VARIANT_TYPE_UNDEFINED = PURC_VARIANT_TYPE_FIRST,
#define PURC_VARIANT_TYPE_NAME_NULL         "null"
    PURC_VARIANT_TYPE_NULL,
#define PURC_VARIANT_TYPE_NAME_BOOLEAN      "boolean"
    PURC_VARIANT_TYPE_BOOLEAN,
#define PURC_VARIANT_TYPE_NAME_NUMBER       "number"
    PURC_VARIANT_TYPE_NUMBER,
#define PURC_VARIANT_TYPE_NAME_STRING       "string"
    PURC_VARIANT_TYPE_STRING,
#define PURC_VARIANT_TYPE_NAME_OBJECT       "object"
    PURC_VARIANT_TYPE_OBJECT,
#define PURC_VARIANT_TYPE_NAME_ARRAY        "array"
    PURC_VARIANT_TYPE_ARRAY,
#define PURC_VARIANT_TYPE_NAME_SET          "set"
    PURC_VARIANT_TYPE_SET,
　
    /* XXX: change this if you append a new type. */
    PURC_VARIANT_TYPE_LAST = PURC_VARIANT_TYPE_SET,
} purc_variant_type;
　
#define PURC_VARIANT_TYPE_NR \
    (PURC_VARIANT_TYPE_LAST - PURC_VARIANT_TYPE_FIRST + 1)

注意，在上述枚舉量的定義中，還使用了將字符串常量和枚舉量置于上下兩行進行定義的技巧。這一技巧既方便了代碼的維護，也能幫助我們在改變一個類型或新增一個類型時，確保對枚舉量和對應的字符串常量做同步處理。