下一節:,上一節:,上一層:撰寫 C   [目錄][索引]


5.2 為你的工作加上註解

每個程式都應該以註解開頭,簡短說明其用途。範例: ‘fmt - 簡單文字填充的過濾器’。此註解應位於包含程式 ‘main’ 函數的原始碼檔案頂部。

此外,請在每個原始碼檔案的開頭撰寫簡短註解,包含檔名以及一兩行關於檔案整體用途的說明。

請以英文在 GNU 程式中撰寫註解,因為英文是幾乎所有國家/地區的程式設計師都能閱讀的唯一語言。 如果你的英文寫得不好,請盡你所能用英文寫註解,然後請其他人協助重寫。 如果你無法用英文寫註解,請找人與你合作,將你的註解翻譯成英文。

請在每個函數上加上註解,說明函數的作用、取得哪些種類的參數,以及參數可能的值的含義和用途。 如果 C 類型以其慣用方式使用,則無需以文字重複 C 參數宣告的含義。 如果其使用方式有任何非標準之處(例如,類型為 char * 的參數實際上是字串的第二個字元的位址,而不是第一個字元),或者任何可能的值會產生與預期不同的結果(例如,不保證包含換行符號的字串能正常運作),請務必說明。

如果有的話,也請解釋回傳值的意義。

請在註解中每個句子的末尾放置兩個空格,以便 Emacs 的句子命令可以運作。 此外,請撰寫完整的句子並將第一個單字大寫。 如果小寫識別字出現在句子的開頭,請勿將其大寫! 更改拼寫會使其成為不同的識別字。 如果你不喜歡以小寫字母開頭句子,請以不同的方式撰寫句子(例如,「識別字 lower-case 是…」)。

如果你使用參數名稱來談論參數值,則函數上的註解會更清楚。 變數名稱本身應為小寫,但是當你談論的是值而不是變數本身時,請以大寫字母撰寫。 因此,使用「inode 號碼 NODE_NUM」而不是「一個 inode」。

通常在函數之前的註解中重複函數名稱是沒有意義的,因為讀者可以自己看到。 當註解太長以至於函數本身會超出螢幕底部時,可能會是一個例外。

每個靜態變數也應該有註解,像這樣

/* Nonzero means truncate lines in the display;
   zero means continue them.  */
int truncate_lines;

每個 ‘#endif’ 都應該有註解,除非是簡短的條件式(只有幾行)且未巢狀的情況。 註解應說明正在結束的條件式的條件,包括其含義。 ‘#else’ 應該有一個註解,描述後續程式碼的條件和含義。 例如

#ifdef foo
  …
#else /* not foo */
  …
#endif /* not foo */
#ifdef foo
  …
#endif /* foo */

但是,相比之下,對於 ‘#ifndef’,請以這種方式撰寫註解

#ifndef foo
  …
#else /* foo */
  …
#endif /* foo */
#ifndef foo
  …
#endif /* not foo */

下一節:,上一節:,上一層:撰寫 C   [目錄][索引]