写点什么

注释还是不注释,这是个问题

  • 2010-03-11
  • 本文字数:1987 字

    阅读完需:约 7 分钟

每个开发者都曾在代码中写过注释,有些人的注释很多,为的就是更好地说明代码的意图。本文搜集了关于编写代码注释的一些实践以飨各位读者。

最近, Seattle Area Alt.Net 小组的成员们就编写代码注释的必要性和实践进行了激烈的讨论。Kelly Leahy 坚持少写注释并编写能够自我说明的代码,因为他相信注释“只会向系统中引入不和谐的声音;一旦修改代码,那些注释就入土为安了”:

编写注释对于大多数人来说是个人的事情,但我本人非常反对写注释,因为一旦修改代码,那些注释就入土为安了——这种情况我见得太多了:注释还在那儿,但代码早就被删除了或是描述的行为被删掉了、代码并没有紧跟注释之后(因为有人在注释和原来的代码之间插入了新的代码)、注释和代码不一致,因为代码被修改了而注释却没有变化。 我觉得这种注释比不写注释还恶心,我憎恨注释。

Leahy 并没有完全否定注释的作用,但他只对 10,000 行代码写了一行注释:

有时注释还是很有用的,比如设计上有不可避免的约束(性能变化等)时就可以加上一些注释。我尽量不写注释,我们大概每 10,000+ 行代码会写一行注释(除了无聊的 xmldoc 注释,我个人觉得这种注释只对于 public API 有用,别的地方一无是处)。

Justin Rudd 说他得在目前所从事的项目中写大量注释,因为里面的 API 实在是“太糟糕了”:

目前我正为 Visual Studio 编写一个源代码控制包。API 实在是太糟糕,没办法只能多写注释了,这样我就能想起来为什么在一个地方需要传递 Guid.Empty 而在另一个地方(看起来很相似的地方)需要传递一个特殊的 GUID,否则一切就都乱套了。 我对实现的 4 个解决方案事件接口加了注释,这样后面的人即便是看到 7 个方法中有 6 个似乎没用也不会把他们删掉了。

我对方法为何要返回一个特定的 HRESULT 加了注释,因为如果返回 S_OK 的话 Visual Studio 会崩溃(Connect 中是这么说的)。

虽然文档说可以传递 null,但你不能这么做,我在这个地方加了注释。

在这个项目中,代码与注释的比例为 2:1。

Chris Tavares 使用注释来标明 bug 被修复了:

注释”// doing this because it fixes bug #####“并不是一种坏味道——事实上这是必要的。

然而 Brandon Molina 认为在代码中通过注释来标明修复的 bug 并不好,使用版本控制系统才是上策:

如果修复了 10 个 bug 该怎么办呢?代码将充斥着大量无用的信息。在这种情况下应该使用版本控制。注释加上 diff 才是明智之举。

Brad Wilson 补充了一条原则以避免差劲的注释:

“Why”注释 == good “How”注释 == suspect

Timo Hilden 写了一篇关于代码注释的文章,他坚持认为好的注释是非常有必要的:

不理会代码注释很容易,但还是让我们面对它吧。作为程序员,我们不指望获得普利策奖(普利策奖是由美国颁发的一个奖项,主要用于奖励那些在新闻报道、文学创作以及音乐创作方面有杰出贡献的人,该奖项由美籍匈牙利人约瑟夫 普利策创建,现在由位于纽约的哥伦比亚大学负责——译者注),因此写不写注释与表达能力强不强没有什么关系,这仅仅事关懒惰与否。 坦白地说,更糟糕的是在代码需要注释的时候却没有编写。首先,这间接地说明了程序员缺少对同伴的尊重。每个人都知道查看大量的类是多么不爽的一件事,尤其是其中包含很多含义模糊、自我描述性差的函数,更有甚至,之前编写代码的人度假去了、离职了或是由于其他原因找不到了。程序员应该是个艺术家而同伴则是其观众。作为艺术家,应该尊重我们的观众。

其次,不写注释表明程序员太过于自负了。当然了,在写代码的时候我们很清楚自己在干什么,编程的时候脑子里会有很多想法,但下一次再看自己所编写的代码时将很可能无法找回当初的想法。以上这些都是常事,这需要我们在适当的地方编写具有描述力的注释。

Hilden 并不赞同取消文档(几年前由 Scott Swigart Jeff Atwood 提出的观点)的做法,看看下面这个过度注释的代码片段:

复制代码
// Declare category id for products
const int prodCategoryId = 1024;
// Create an iterator over products
vector<Product>::iterator iter = products_.begin();
// Iterate through all products
for ( ; iter != products_.end(); ++iter )
{
// Assign categody id to each product
iter->AssignCategoryId( prodCategoryId );
}

他建议将上面这些注释合并成一行用于说明代码的总体意图而非每行的意思:

复制代码
// Assign categody id to each product
const int prodCategoryId = 1024;
vector<Product>::iterator iter = products_.begin();
for ( ; iter != products_.end(); ++iter )
{
iter->AssignCategoryId( prodCategoryId );
}

各位读者,你采取何种手段编写注释呢?这些方法是公司的硬性规定还是自己选择的呢?你支持“编写尽可能少的注释”这种观点么?是否相信后继者能理解你所编写的代码么?你认为程序员是否需要花时间对代码中那些不太好理解的地方加注释么?

查看英文原文: To Comment or Not to Comment

2010-03-11 08:094036
用户头像

发布了 88 篇内容, 共 268.8 次阅读, 收获喜欢 8 次。

关注

评论

发布
暂无评论
发现更多内容

面对营销难,有米云指出一条破局之路

ToB行业头条

官网应用开发文档及学习资源7月上新汇总

HarmonyOS开发者

HarmonyOS

暑气渐敛,8月让我们开源一夏!

InfoQ写作社区官方

开源 热门活动 8月月更

分布式一致性如何实现?- Raft 算法

了凡跨境洞察

分布式 微服务架构 raft 一致性算法 一致性

2.8K 120Hz触控双屏加持 灵耀X 双屏Pro 2022让办公无惧想象

科技热闻

直播app开发,是优化直播体验不得不关注的两大指标

开源直播系统源码

软件开发 直播系统源码 语音直播系统源码 直播app

Git 不要只会 pull 和 push,学学这 5 条提高效率的命令(下)

CRMEB

DBPack SQL Tracing 功能及数据加密功能详解

峨嵋闲散人

分布式事务 分库分表 读写分离 dbmesh Database Mesh

设计专业第一台笔记本 华硕灵耀Pro16 2022 新品首发超值入手

科技热闻

未来小间距竞争的着力点在哪里

Dylan

LED显示屏 led显示屏厂家

基于BiGRU和GAN的数据生成方法

行者AI

人工智能

java培训学习怎么样?

小谷哥

BPM是什么意思?BPM的优势及好处有哪些?

优秀

BPM

OneFlow源码解析:Op、Kernel与解释器

OneFlow

深度学习 源码解析

LeaRun.net快速开发动态表单

力软低代码开发平台

“查找附近的商铺”|Geohash+MySQL实现地理位置筛选

领创集团Advance Intelligence Group

MySQL sql geohash

选择合适的 DevOps 工具,从理解 DevOps 开始

飞算JavaAI开发助手

开源一夏 | 五分钟带你上手ShardingJDBC实现MySQL分库分表

知识浅谈

开源 8月月更

30分钟成为Contributor|如何多方位参与OpenHarmony开源贡献?

OpenHarmony开发者

Open Harmony

浅谈游戏音效测试点

行者AI

游戏测试

研发团队数字化转型实践

思码逸研发效能

研发效能 数字化

百图生科卓越开发者计划全面升级暨《计算免疫问题白皮书》发布

硬科技星球

Rancher 部署 DataKit 最佳实践

观测云

TiFlash 存储层概览

TiDB 社区干货传送门

数据库 分布式数据库 TiDB

浅谈大数据背景下数据库安全保障体系

阿炜小菜鸡

数据库

今年最火爆的词:商业分析,看这一篇就够了!

博文视点Broadview

兆骑科创科创赛事平台,创业赛事活动路演,线上直播路演

兆骑科创凤阁

80篇国产数据库实操文档汇总(含TiDB、达梦、openGauss等)

墨天轮

数据库 opengauss TiDB 国产数据库 南大通用

AntDB数据库亮相24届高速展,助力智慧高速创新应用

亚信AntDB数据库

AntDB 国产数据库 aisware antdb

分析Flask WSGI经过Nginx代理出现两次302问题

西北望高楼

flask Python.

实战模拟│微信 JSSDK 实现自定义分享、手机选图拍照、图片音频处理、地理位置、摇一摇等功能

经验分享 微信开发 签约计划第三季 8月月更 jssdk

注释还是不注释,这是个问题_架构_Abel Avram_InfoQ精选文章