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

与本文有关的任何建议或意见，请Email至：[email protected] 我将持续改进这篇文章。

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

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

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