禅道博客

分享专业技术知识,文章内容干货满满

Linux之父:连你自己都懒得解释,那这就是一堆垃圾!

2023-03-24 11:06:18
霍格沃茨青岛分校
原创 952
摘要:不出意外,Linus又开喷了!
不出意外,Linus又开喷了,这次的激情开麦,源自一部分没有做注释的合并请求:Linux6.3内核收到了一部分合并请求,但这部分合并完全没有注释

如果你懒得解释为什么存在一个合并,那这个合并从本质上来说就是错误的垃圾,这是每个开发者都应牢记于心的规则。我重复一遍:如果你不能解释清楚这个合并请求,那就不要做,就是这么简单。——Linus Torvalds  
让Linus如此生气的代码注释,到底有啥用?

注释不仅展现了代码背后的逻辑,让我们在后期维护时能更容易阅读、理解代码,还能将授权许可、版权信息编写进去。此外,注释也有提示作用,如标记为FIXME或TODO的注释往往表示待定的工作等等。

总之,代码注释告诉了我们为什么会写这样的代码。对Linus来说,收到的合并请求缺乏注释,因为没有合理的解释,代码不仅变得毫无意义,还会变得更难读、难维护。所以代码注释很重要,编写合理的代码注释更重要。

编写注释,快看这三不要!

1.不要花大力气编写注释,解释代码的每一个细节!

过多的注释会让源文件变得非常混乱,不仅会降低代码的可读性,还难以维护。(这种写大量注释的行为,也很难不让Linus发火。)

2.不要留不恰当的注释!

很多人会通过注释保存代码演变的历史记录,但这往往是无用功。一个热知识:版本控制系统可以保存历史记录。还有一些过时的、被废弃的、不正确的注释,一经发现就需要尽快更新或删除,不能再让这些废弃注释误导我们了!
 

3.不要犹豫!看到注释掉的代码,请直接删掉它!

对于那些不再使用的旧代码,大家可能下意识会直接注释掉,但直接干脆利落删除掉这些旧代码会更简洁。毕竟后期维护的时候,大家面对这些注释掉的代码只会敬而远之。

重构吧!

通过重构那些烂代码,可以摆脱不必要的注释:
  • 命名:比如将变量i重命名为numGoals,能明确意图。对于变量、方法以及类,我们都可以这样做;
  • 结构:如果某一段代码没有注释就无法理解,可以尝试更改代码结构;
  • 子表达式:将一个复杂的表达式拆分为多个子表达式,可以帮助大家更好地理解代码;
  • 断言:当我们遇到“当某个条件为真时,某段代码才能正常运行”的情况时,可以引入断言标明假设。
这样才能使注释更简洁、易看。

如何编写好的代码注释?

以下几个注释模式送给大家:
  • 文档注释模式:记录接口,而不是解释代码本身。
  • 脚注注释模式:主要用于描述为什么采用特定方法,短小精悍。通常在无法从代码中推断出此类信息的情况中使用。
  • 警告注释模式:警告开发人员注意某些特殊需求的注释,如:以超级管理员的身份调用函数。警告可能涉及安全或设计缺陷,注释可能包括TODO或FIXME。
  • 签名注释模式:注释中加上开发人员的首字母缩写。在团队中,我们可以更快速地找到相应人员讨论。
  • 编织代码模式:代码和文档结合在一起。需要首先编写文档,然后对该文档进行编码。

在Linus看来,写代码非常重要,写好的代码更重要。注释、命名、版式等代码规范检验的正是程序员最重要的基本功,如果基础不牢,必定地动山摇。关于代码规范,你还有什么想要了解的?欢迎观看代码规范小视频
暂时没有记录
评论通过审核后显示。