转载

写好你的注释

C语言是一门儿好的编程语言。它可以被写得很优美，也可以被写得很混乱。只不过大家都想看写得优美的C程序，除非你要参加C语言混乱代码大赛。如果你现在还不了解什么是C语言混乱代码大赛，我劝你赶紧搜索一下，这是一个真实存在并且有趣儿的国际比赛。

好吧，如果哪天你的C程序出了问题，你拿给我看：

#include "stdio.h"
#define _(x) myfun(x)
int _(int);main(){int i=1;for(;i==0;)printf("a""b""c");i++;printf("%d",i);if(i==1)printf("!");printf("%d",_(i));}int myfun(int a){int i;printf("a");printf("%da",a);for(i=2*a;i<a;i--)printf("A");return a+i;}

放心！我并不会像那些脾气不好的人一样冲你发火，我只是会打开播放器极乐净土单曲循环，接着把你从代码复制到我的集成开发环境中。然后点一下格式化当前文件。于是我就得到了一个能凑合看的代码：

#include "stdio.h"
#define _(x) myfun(x)
int _(int);
main() {
    int i=1;
    for(; i==0;)printf("a""b""c");
    i++;
    printf("%d",i);
    if(i==1)printf("!");
    printf("%d",_(i));
}
int myfun(int a) {
    int i;
    printf("a");
    printf("%da",a);
    for(i=2*a; i<a; i--)printf("A");
    return a+i;
}

然后我会手工帮你修改程序，并且把这样一个程序传给你：

#include "stdio.h"

extern int myfun(int a);

int main()
{
    int i=1;
    while(i==0)
    {
        /*
        ** 这个循环永远不会被执行到
        **/
        printf("abc");
    }
    i++;
    /*
    ** 输出i的值
    **/
    printf("%d",i);
    if(i==1)
    {
        printf("!");
    }
    /*
    ** 调用myfun函数并输出它的返回值
    **/
    printf("%d",myfun(i));
    return 0;
}

/*
** myfun函数:意义不明
** 需要一个int参数
** 返回一个int值
**/
int myfun(int a)
{
    int i=0;
    /*
    ** 输出字符a，变量a的值，字符a
    **/
    printf("a");
    printf("%da",a);

    for(i=2*a; i<a; i--)
    {
        /*
        ** 如果a是负数就不停的输出字符A
        ** 否则就不会进入这个循环
        **/
        printf("A");
    }
    /*
    ** 结束，并返回a+i的值
    ** 如果能到这里i等于两倍的a
    **/
    return a+i;
}

一般情况下，如果我帮你改的程序都会用注释的方式写出来你需要注意的东西，还有一些问题。你会发现我不使用 // 进行注释，而是使用 /* */ 这儿有几个不够充分的理由和非常充分的理由来告诉你我为什么这样做。

其中一个不够充分的理由是： // 是从C++才引入的，或者说C语言的前身BCPL中本来是有 // 。但是我不喜欢使用 // 。

另一个不够充分的理由是：我有时候会搞不清楚 // 和除号的 / 它总是让我看花眼。所以我不喜欢它。毕竟有的时候我需要在没有集成开发环境的地方写代码，或者说没有高亮工具，譬如说在纸上写程序的时候。

那些不够充分的理由我能说出来一大堆，不过一个充分的理由是：我从来不把注释行和代码混写在一行，对于我来说 // 是暂时跳过某一行的代码的意思，而 /* */ 才是真正的注释。

我建议你也这样做，虽然不是强制的，但是一旦你这样做了。你就会发现无论有没有高亮，即使你用黑白打印机把源码印刷出来。你仍然很容易识别那些是你是注释。

现在总有一些程序员认为应该让程序的可读性代替冗长的注释，我估计他八成不是上个世纪就开始学习程序的人。如果你是上个世纪就开始接触这些玩意儿的人，你一定知道。你很难碰到一台那么完美的机器。在上个世纪我们都非常小心的使用循环。包括我到现在也有这个毛病，能使用一层循环完成的工作绝对不使用嵌套。虽然现在的计算机绝对不会因为多几个循环就卡死。但是如果你使用大规模的递归，它仍然有可能被卡死。所以在你学习组合数学这门儿课的时候，教授就应该警告过你尽可能用别的方法代替递归。当然了，你听到这句警告也可能在你的算法课上。

无论如何，注释是非常重要的东西，你有必要告诉两个月之后你自己以及你之后需要维护这个程序的所有程序员这些玩意儿到底是在干什么。你想要的结果是什么，目的是什么。你写一个函数应该用注释的方式标出它的功能以及常规的使用方法。以避免你的程序万一出了什么岔子，之后的程序员好在不损害关键功能的情况写帮你改写代码。而不是自以为是的写成一坨，然后让别人去读懂你写的东西。毕竟如果你已经做上了程序员的工作，你就会知道改代码或者叫调程序的时间要比你写程序的时间多的多。几乎你一个月里面只有几天在写程序，其他时间都在调试它，让它从勉强能动起来变得健壮。如果你想进一步知道你应该怎么写注释以及怎么写出来漂亮的程序，就关注我的微信公众号yevgeny_liu，或者是扫描下面这个二维码。

写好你的注释