一场关于代码注释的争执,引发的三点思考

简介: 在一次研发沟通会上,大家关于是否需要代码注释做了一番争执(讨论)。

在一次研发沟通会上,大家关于是否需要代码注释做了一番争执(讨论)。


微信图片_20220608113848.jpg


主要内容简述如下:


A:我提议项目应该有个注释,我们有些程序员几乎从不注释代码,谁都知道没注释的代码是没法阅读的。

B:我觉得注释没必要,注释被当做万灵药,可是任何实际编码过的人都知道,注释反而会使代码更难读懂。注释很容易产生大量的废话,而编码语言相对简明扼要得多。

C:是这么回事。假如代码不清晰,又怎能注释的清楚呢?再说,代码一变,注释就过时。要是误读了过时的注释,可能又会踩坑了。

C 接着说:另外,注释过多的代码更难读懂,这样增大了阅读量。已经有一堆代码要去读了,何必再去读一大堆注释呢?

A:编辑器要知道的东西全在代码中?二进制文件里面吗?争论注释有无价值干啥呢?

B:我反对注释主要是觉得浪费资源。

D:也不能这么说,注释可能会被滥用,但是注释用得好时却妙不可言。另外,在我的工作经历中,有注释和没注释的我都维护过,我个人还是更愿意维护有注释的代码。最后补一句:尽管没必要制定注释的标准,但是我还是提倡大家注释好自己的代码。

........


关于是否加注释争执讨论比较久,最终大家统一了如下决定:


“提倡加注释,但不能滥用。我们开发流程中会有Code Review过程,这样每个人都将了解好的注释是什么样的,同时你遇到不好的代码注释,也需要告诉他如何改进。”


问题思考


作为研发同学,对于代码“注释”其实并不陌生。它往往作为我们代码文档的特殊补充而存在。


其实在代码文档中,起主要作用的因素并非注释,而是好的编程风格。


编程风格包括:良好的程序结构、易于理解的方法、有意义的变量名和子程序名、常量、清晰的布局,以及最低复杂度的控制流及数据结构。


会后我就在反思:那注释真的是以啰嗦的方式又重复一遍代码,所以没有用么?


好注释可不是重复代码或者解释代码,它会让作者的意图更清晰,注释应该能在更高的意图上解释你想干什么。


日常的注释


微信图片_20220608113850.jpg


一般情况下,注释写的糟糕很容易,写的出色就很难了。注释不好只会帮倒忙。


我们来看几个例子:


// write out the sums 1..n for all n from 1 to num
current = 1;
previous = 0;
sum = 1;
for(int i=0; i<num; i++){
  System.out.Println("Sum = " + sum);
  sum = current + previous;
  previous = current;
  current = sum;
}


其实这段代码计算的是斐波那契(Fibonacci)数列的前num个值。如果注释错了,盲目相信注释可能会南辕北辙,但是好的注释会事半功倍。


// compute the square root of num using the Newton-Raphson approximation
r = num / 2;
while(abs(r - (num/r) > TOLERANCE){
  r = 0.5 * (r + (num/r));
}
System.out.println("r = " + r);

上述例子,它用来计算num的平方根,代码一般,但注释比较精准。


注释的目的


写代码和注释的第一目的是帮助人理解代码,理解作者的意图。


所以优秀的代码本身就有自说明功能,只有在代码本身无法清晰地阐述作者的意图时,才考虑写注释。


即是:注释应该表达我的代码为什么要这么做,而不是表达我的代码做了什么


我们软件开发过程中引入了那么多的设计模式、框架、组件,开发过程制定了那么详细的设计规范、编码规范、命名规范、很大一部分原因就是为了提高代码的可读性。


编程语言特别是高级编程语言,本身就是人和机器之间沟通的语言,语言本身就要求满足人的可读性,需要用符合我们自然语言的表达习惯,不需要额外的注释。

注释怎么写?


当然,好代码 > 差代码+好注释,好的注释是很有价值的,坏注释不仅浪费时间还可能有害,自解释的代码最好。


当然,好代码 > 差代码+好注释,好的注释是很有价值的,坏注释不仅浪费时间还可能有害,自解释的代码最好。好的注释不是重复代码或解释它,而是使代码更清楚,注释在高于代码的抽象水平上解释代码要做什么事。


具体的操作手段,包括但不限于以下几点:


  • 适当注释,仔细衡量,不要隐晦也不要多余;


  • 注意存在变更情况是,需要及时更新;


  • 注释代码中一些tricky的技巧或者特殊的业务逻辑,否则会让读代码的人摸不着头脑;


  • 如果附上jira、bug、需求等的地址能够帮助理解代码,可以适当加上;


  • 如果代码命名良好,结构合理,一般来说是不需要什么注释的。但是用一句话解释下意图和功能也是极好的,因为很多时候仅仅是想知道代码怎么用,读一句注释要比分析几十行代码快得多。

注释的原则


1)写注释应遵循奥卡姆剃刀原则:如无必要,勿增实体


注释写的不好、维护得不好(比如改了代码没改注释)会导致代码的可读性变差。


2)有句话叫“代码即注释”,虽然不完全是,但有道理的


把代码写好、写漂亮,注释就可以精炼,也必然能写得更易懂。此外,把思路(难的、关键的)写清楚,比啥Author、Date重要多了。抓重要信息。


3)建议注释里尽量写为什么,而不是做了什么


做了什么,看代码就好,代码不会骗人。但为什么要写成这样,有时候就非常让人困惑。有可能是处理某个corner case,有可能是绕过某个系统限制,也可能是什么奇葩需求,这种代码,没有当时的 context,过几个月看,像甲骨文一样,不知道是想干什么。再有看不顺眼来优化一下,以后就不知道哪个地方会崩了。


其实,大部分的代码应当是不言自明的,不需要注释的。


总结


  • 好的注释才有价值


该不该注释是个需要认真对待的问题。差劲的注释只会浪费时间。好的注释才有价值。注释的位置可以在:变量特定的含义和限制、某个职责代码块的开始、一般控制结构的开始、子程序调用处、方法开始处描述功能、类开始处描述功能。


  • 源代码应当含有程序大部分的关键信息。


只要程序依然在用,源代码比其他资料都能保持更新,故而将重要信息融入代码是很有好处的。


  • 好代码本身就是最好的说明


如果代码太糟,需要大量注释,应先试着改进代码,直至无须过多注释为止。


  • 注释应说出代码无法说出的东西


例如概述或用意等信息。注释本身应该包含的是对代码的简洁的抽象概括,而不是具体代码的实现细节。


  • 注释风格也应该简洁易于维护


有的注释风格需要许多重复性劳动,应舍弃之,改用易于维护的注释风格。


微信图片_20220608113854.jpg

相关文章
|
6月前
|
设计模式 算法 前端开发
有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
有什么可以减少注释,但依然能让他人看得懂代码的方法吗?
56 0
|
3月前
|
Java Android开发
Android项目架构设计问题之要提升代码的可读性和管理性如何解决
Android项目架构设计问题之要提升代码的可读性和管理性如何解决
38 0
|
4月前
codereview开发问题之CodeReview中如何判断注释问题如何解决
codereview开发问题之CodeReview中如何判断注释问题如何解决
|
自然语言处理 Java 机器人
从细节出发:提高你的代码可读性
在编程的世界中,我们总是不断追求更高的性能,更优雅的设计,以及更复杂的特性。然而,我们不应忽视一个基本且重要的原则——代码的可读性。那么究竟何谓代码的可读性?顾名思义,代码可读性是指代码可理解的程度,是代码作者通过代码这个媒介,将需要表达的信息输出到读者脑中的能力。所以有的人说好的代码必然有清晰完整的注释,也有人说代码即注释,是代码简洁之道的最高境界,后者的观点飞哥持保留意见,毕竟真正能够做到代码即注释的有几人呢?
|
6月前
|
前端开发 测试技术
代码注释怎么写:让你的代码更易维护
在编程中,有一种无声的艺术,那就是代码注释。这可能看起来微不足道,但其实非常关键。它不仅有助于他人理解你的代码,也是自我表达的一种方式。
|
6月前
|
设计模式 算法 程序员
如何写出好的代码注释?
作为程序员,想必大家在日常开发中必写注释,而且在软件开发过程中,给代码写注释是一项至关重要的工作,也是一名合格的程序员该具备的编程素养。恰当的注释可以提高代码的可读性和可维护性,方便其他人理解熟悉和修改代码,但是不恰当或过度的注释可能会导致混乱和误导,会起到适得其反的作用。那么本文就来分享一些关于如何正确地给代码写注释的方法和指导原则,并提供一些减少注释但仍能让他人理解代码的方法。
145 3
如何写出好的代码注释?
|
6月前
|
Java
注释之背后:代码的解释者与保护者
注释之背后:代码的解释者与保护者
39 0
|
人工智能 自然语言处理 Java
提高代码可读性的秘诀:注释的重要性
A:你写代码怎么连注释都不加? B:老大为什么要加注释? A:你不加注释,你怎么知道我能看懂你的代码? B:遇到问题你找到就可以了啊? A:那你哪天生病了请假了闹情绪了离职了,公司怎么办? B:我现在反正没觉得有什么问题,我对公司也很满意,安心啦! 又是00后整顿职场的一段精彩演绎。不可置否,在实际的软件开发过程中,确实有很多开发人员依然不愿意写注释认为这会浪费时间,或者自认为他们的代码足够清晰,不需要额外的解释。但这种想法too young too simple,代码注释对于项目的质量和效率有着深远的影响,在软件开发中的重要性不容小觑。
|
程序员
相见恨晚的Matlab编程小技巧(2)-代码怎么做到逻辑清晰?——巧用注释符“%“
        本文将以教程的形式详细介绍Matlab中两个常用符号“%”和“%%”的作用。初学者可以通过此文掌握这两个符号的用法,为Matlab编程打下坚实的基础。
花五分钟把代码注释也规范一哈子?
从技术上来说没有对错,理论上,你想怎么写就怎么写,你爱怎么写就怎么写! 但它确实也会对我们造成影响,尤其是在多人协同开发的系统中。杂乱的注释也会让你或你的队友头疼~ 所以,我们需要规范一下注释。那什么才是好的注释呢?我们先来看看什么是不好的注释!