Linux之父:连你自己都懒得解释,那这就是一堆垃圾!
不出意外,Linus又开喷了,这次的激情开麦,源自一部分没有做注释的合并请求:Linux6.3内核收到了一部分合并请求,但这部分合并完全没有注释。
如果你懒得解释为什么存在一个合并,那这个合并从本质上来说就是错误的垃圾,这是每个开发者都应牢记于心的规则。我重复一遍:如果你不能解释清楚这个合并请求,那就不要做,就是这么简单。——Linus Torvalds
让Linus如此生气的代码注释,到底有啥用?
注释不仅展现了代码背后的逻辑,让我们在后期维护时能更容易阅读、理解代码,还能将授权许可、版权信息编写进去。此外,注释也有提示作用,如标记为FIXME或TODO的注释往往表示待定的工作等等。
总之,代码注释告诉了我们为什么会写这样的代码。对Linus来说,收到的合并请求缺乏注释,因为没有合理的解释,代码不仅变得毫无意义,还会变得更难读、难维护。所以代码注释很重要,编写合理的代码注释更重要。
编写注释,快看这三不要!
1.不要花大力气编写注释,解释代码的每一个细节!
过多的注释会让源文件变得非常混乱,不仅会降低代码的可读性,还难以维护。(这种写大量注释的行为,也很难不让Linus发火。)2.不要留不恰当的注释!
很多人会通过注释保存代码演变的历史记录,但这往往是无用功。一个热知识:版本控制系统可以保存历史记录。还有一些过时的、被废弃的、不正确的注释,一经发现就需要尽快更新或删除,不能再让这些废弃注释误导我们了!3.不要犹豫!看到注释掉的代码,请直接删掉它!
对于那些不再使用的旧代码,大家可能下意识会直接注释掉,但直接干脆利落删除掉这些旧代码会更简洁。毕竟后期维护的时候,大家面对这些注释掉的代码只会敬而远之。
重构吧!
通过重构那些烂代码,可以摆脱不必要的注释:- 命名:比如将变量i重命名为numGoals,能明确意图。对于变量、方法以及类,我们都可以这样做;
- 结构:如果某一段代码没有注释就无法理解,可以尝试更改代码结构;
- 子表达式:将一个复杂的表达式拆分为多个子表达式,可以帮助大家更好地理解代码;
- 断言:当我们遇到“当某个条件为真时,某段代码才能正常运行”的情况时,可以引入断言标明假设。
这样才能使注释更简洁、易看。
如何编写好的代码注释?
以下几个注释模式送给大家:- 文档注释模式:记录接口,而不是解释代码本身。
- 脚注注释模式:主要用于描述为什么采用特定方法,短小精悍。通常在无法从代码中推断出此类信息的情况中使用。
- 警告注释模式:警告开发人员注意某些特殊需求的注释,如:以超级管理员的身份调用函数。警告可能涉及安全或设计缺陷,注释可能包括TODO或FIXME。
- 签名注释模式:注释中加上开发人员的首字母缩写。在团队中,我们可以更快速地找到相应人员讨论。
- 编织代码模式:代码和文档结合在一起。需要首先编写文档,然后对该文档进行编码。