质疑和反驳

为代码写足够的注释,让代码易于理解

“所有程序员都会写自己看得懂的代码,但只有优秀的程序员才写大家看得懂的代码。”

这话没错,但是——什么才是“大家看得懂”的定义?我有必要让我的C++代码对于一个月前才明白指针和引用区别的初学者简单易懂么?

更重要的是,要代码能够“看得懂”,主要是靠足够多的注释吗?扯淡!

反对我的人会说,软件公司做产品赚钱,它们希望你的代码让不熟悉项目的新员工快速阅读、上手。这确实是个矛盾。说白了,你写的代码要和一个团队的能力匹配。在一个鱼龙混杂的团队,甚至一个糟糕的团队,你写出的代码也许很难和大伙儿产生共鸣,他们希望你写最普通最易懂的代码,没有精巧的设计(我指的是,“某一些精巧的设计,恰恰是以降低代码的可维护性为代价的”),没有语言高级特性,看着只有顺序、循环、分支判断的基本代码。

所以许多上进的程序员,会希望在一个牛人的团队里工作。这就像足球运动员一样,因为足球是集体运动,一个足球运动员能达到的高度,是和他所在的团队息息相关的。在一个优秀的团队里,大家个性各有千秋,擅长领域不甚相同,但是都学习迅速,能力不差太远,大家阅读代码都能够很快理解和领会,而且讨论问题可以用一些程序员才明白的隐喻(比如有人说“我觉得这里应该用一个builder来实现”,大家都明白builder指的是什么),氛围和效率显而易见。

如果你恰好对当前需要用到的业务和技术特别熟悉,领先团队里其他人一大截怎么办?那你就该在做设计编码的时候先行一步,你是那个最该去做架构设计、写骨架代码的人,完成一个架子以后再来给大家讲解,并和大家讨论,改进现有的设计。也就是说,你要多做一些更重要的事,而不是和大家一起分析、一起讨论,甚至一人负责一个模块,最后的结果就是大家根本和你讨论不到一块儿去。

要代码“看得懂”,是设计出来的,而不是注释加出来的。这和产品质量一样,产品质量是设计出来的,而不是测试测出来的。注释的意义在于对当前代码自解释做不到的地方进行补充。

所以,你的代码要易于理解,首先要保持简洁和清晰,这既包括良好的设计,也包括良好的编码习惯,也就是说,代码是自解释的,其次才通过注释的补充,让代码更易懂。注意,我不是说注释不重要和不必要,而是说,注释应该完成它自己的功用,它远不能代替代码本身自我解释的价值。

举一个简单的例子,你可以这样写代码:

/**
 * 图表模型
 */
class Chart{
    /**
     * 图表长度
     */
    private int length;   
 
    /**
     * 获取图表长度
     * @return 图表长度
     */
    public int getLength(){
        return this.length;
    } 
 
    /**
     * 设置图表长度
     * @param length 图表长度
     */
 
    public void setLength(int length){
        this.length = length;
    }
}
1 week ago, this page was being read.

,

Subscribe to Comments