C,是一种信仰

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

与本文有关的任何建议或意见,请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.

posted @ 2013-06-06 11:36  胖乎乎的王老师  Views(3210)  Comments(0Edit  收藏
Email 联系我:fzd19zx@qq.com