注釋的作用，以及如何寫注釋

與本文有關的任何建議或意見，請Email至：[e-mail] 我將持續改進這篇文章。

初學者在學習編程的過程中，經常忽略注釋的作用。而當他們意識到注釋的重要性之后，又會產生一個困惑：“我該如何寫注釋？”

但是，這個代碼是做什么用的呢？你就需要注釋來進行說明了。

問題1：為什么我要寫注釋？

答：因為你是人，不是神。
是人，就無法突破人的局限性：善變、善忘、常常出錯……
所以，你需要用注釋來解釋和闡述一下你的程序代碼，以免你自己忘了自己的解題方法。（認為自己從不會忘記的同學，請翻出上個月你寫的代碼，看看它是什么意思？）

問題2：注釋是寫給誰看的？

答：注釋是寫給人（程序員）看的。電腦不在意你的注釋，所以，電腦不會介意下面的代碼：

問題3：如何寫注釋？

答：注釋的作用不在於表示代碼的含義，而在於表示代碼的功能。

下面我給出代碼注釋的幾個原則：

1、變量（特別是存儲關鍵數據的變量），都需要注釋說明變量的意義。

2、不要去注釋“我的代碼做了什么？”，而是要注釋“我的代碼為什么要這么做？”。

下面我們來看幾個例子：

這是一個完整的程序，但是如果沒有注釋，我們很難一眼看出它的作用是什么。

     1 # include "stdio.h"
    2 # define MAX (100)
    3 int main() {
    4     int
    5         a[MAX],
    6         i,
    7         j,
    8         tem;
    9 
   10     for (i=0; i<=9; i++) scanf("%d",&a[i]);
   11 
   12     for (i=0; i<=8; i++)
   13         for (j=i+1; j<=9; j++) {
   14             if (a[i]>a[j]) {
   15                 tem = a[i];
   16                 a[i] = a[j];
   17                 a[j] = tem;
   18             }
   19         }
   20 
   21     for (i=0; i<=9; i++) printf("%d, ", a[i]);
   22 }

於是，我們為它加上注釋。

如果我們這么寫注釋：

    1 int
   2     a[MAX], /* 一個整數數組 */  <-- 廢話，這就是個很爛的注釋。學過C的人，都知道這是一個整數數組。
    3     i,      /* 一個整數 */      <-- 學過C的人，都知道這是一個整數。所以，也是廢話。
    4     j,      /* 一個整數 */      <-- 同上
    5     tem;    /* 一個整數 */      <-- 同上

如果我們像下面這么寫，感覺就好多了：

    1 int
    2     a[MAX], /* 存儲待排序的數據 */      <-- 說明了該數組的作用：“我為什么要這個數組？”
     3     i,
    4     j,
    5     tem;    /* 臨時變量，用於交換 */    <-- 說明了該變量的作用：“我為什么需要這個變量？”

再看代碼部分的注釋。

如果你像下面這么寫，那就是廢話大全：

    1 /* i從0循環到8 */   <--廢話
     2 for (i=0; i<=8; i++)
    3     /* j從1循環到9 */ <--廢話
     4     for (j=i+1; j<=9; j++) {
    5         if (a[i]>a[j]) {
    6             tem = a[i];     /* a[i]賦值給tem */     <--廢話
     7             a[i] = a[j];    /* a[j]賦值給a[i] */    <--廢話
     8             a[j] = tem;     /* tem賦值給a[j] */     <--廢話
     9         }
   10     }

<!--HTML generated by highlight 2.7, ht

如果你改成下面這樣，人家看起來就很舒服：

    1 /* 對a[0..9]進行從小到大的排序 */   <--說明了下列循環的作用
     2 for (i=0; i<=8; i++)
    3     /* 選出a[0..9]中第i小的數，放在a[i]中 */  <--說明了下列循環的作用
     4     for (j=i+1; j<=9; j++) {
    5         if (a[i]>a[j]) {
    6             /* a[i] <==> a[j] */    <-- 簡單的圖示，有時候更能反映代碼的作用
     7             tem = a[i];
    8             a[i] = a[j];
    9             a[j] = tem;
   10     }

最終，代碼看起來像這樣，舒服吧？

    1 # include "stdio.h"
    2 # define MAX (100)
    3 int main() {
    4     int
    5         a[MAX], /* 存儲待排序的數據 */
    6         i,
    7         j,
    8         tem;    /* 臨時變量，用於交換 */
    9 
   10     /* 輸入數據 */
   11     for (i=0; i<=9; i++) scanf("%d",&a[i]);
   12 
   13     /* 對a[0..9]進行從小到大的排序 */
   14     for (i=0; i<=8; i++)
   15         /* 選出a[0..9]中第i小的數，放在a[i]中 */
   16         for (j=i+1; j<=9; j++) {
   17             if (a[i]>a[j]) {
   18                 /* a[i] <==> a[j] */
   19                 tem = a[i];
   20                 a[i] = a[j];
   21                 a[j] = tem;
   22             }
   23         }
   24 
   25     /* 輸出結果 */
   26     for (i=0; i<=9; i++) printf("%d, ", a[i]);
   27 }

That’s all. Thanks for reading.