注释的作用，以及如何写注释

与本文有关的任何建议或意见，请Email至：fzd19zx@gmail.com 我将持续改进这篇文章。

初学者在学习编程的过程中，经常忽略注释的作用。而当他们意识到注释的重要性之后，又会产生一个困惑：“我该如何写注释？”

但是，这个代码是做什么用的呢？你就需要注释来进行说明了。

问题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.