会写注释才是合格的程序员

前言

上一篇中我们讲了命名,今天我们来讲一下注释(Comments)。注释其实就是针对复杂逻辑代码的解释和说明,解释为什么要这么写,这段代码大概功能是什么。注释的作用是方便阅读代码的人快速理解编写代码的人的思考。

会写注释才是合格的程序员

注释

命名很重要,注释跟命名同等重要。很多书籍认为,好的命名完全可以替代注释。如果需要注释,那说明命名不够好,需要在命名上下功夫,而不是添加注释。实际上,我个人觉得,这样的观点有点太过极端。命名再好,毕竟有长度限制,不可能足够详尽,而这个时候,注释就是一个很好的补充。

1. 注释到底该写什么?

注释的目的就是让代码更容易看懂。只要符合这个要求的内容,你就可以将它写到注释里。总结一下,注释的内容主要包含这样三个方面:做什么、为什么、怎么做。我来举一个例子给你具体解释一下。

/**

* (what) Bean factory to create beans.

*

* (why) The class likes Spring IOC framework, but is more lightweight.

*

* (how) Create objects from different sources sequentially:

* user specified object > SPI > configuration > default object.

*/

public class BeansFactory {

  // ...

}

有些人认为,注释是要提供一些代码没有的额外信息,所以不要写 “做什么、怎么做”,这两方面在代码中都可以体现出来,只需要写清楚 “为什么”,表明代码的设计意图即可。我个人不是特别认可这样的观点,理由主要有下面 3 点。

  • 注释比代码承载的信息更多

命名的主要目的是解释 “做什么”。比如,void increaseWalletAvailableBalance (BigDecimal amount) 表明这个函数用来增加钱包的可用余额,boolean isValidatedPassword 表明这个变量用来标识是否是合法密码。函数和变量如果命名得好,确实可以不用再在注释中解释它是做什么的。但是,对于类来说,包含的信息比较多,一个简单的命名就不够全面详尽了。这个时候,在注释中写明 “做什么” 就合情合理了。

  • 注释起到总结性作用、文档的作用

代码之下无秘密。阅读代码可以明确地知道代码是 “怎么做” 的,也就是知道代码是如何实现的,那注释中是不是就不用写 “怎么做” 了?实际上也可以写。在注释中,关于具体的代码实现思路,我们可以写一些总结性的说明、特殊情况的说明。这样能够让阅读代码的人通过注释就能大概了解代码的实现思路,阅读起来就会更加容易。

实际上,对于有些比较复杂的类或者接口,我们可能还需要在注释中写清楚 “如何用”,举一些简单的 quick start 的例子,让使用者在不阅读代码的情况下,快速地知道该如何使用。

  • 一些总结性注释能让代码结构更清晰

对于逻辑比较复杂的代码或者比较长的函数,如果不好提炼、不好拆分成小的函数调用,那我们可以借助总结性的注释来让代码结构更清晰、更有条理。

public boolean isValidPasword(String password) {

  // check if password is null or empty

  if (StringUtils.isBlank(password)) {

​    return false;

  }

  // check if the length of password is between 4 and 64

  int length = password.length();

  if (length < 4 || length > 64) {

​    return false;

  }

  // check if password contains only lowercase characters

  if (!StringUtils.isAllLowerCase(password)) {

​    return false;

  }

​

  // check if password contains only a~z,0~9,dot

  for (int i = 0; i < length; ++i) {

​    char c = password.charAt(i);

​    if (!(c >= 'a' && c <= 'z') || (c >= '0' && c <= '9') || c == '.') {

​      return false;

​    }

  }

  return true;

}

2. 注释是不是越多越好?

注释太多和太少都有问题。太多,有可能意味着代码写得不够可读,需要写很多注释来补充。除此之外,注释太多也会对代码本身的阅读起到干扰。而且,后期的维护成本也比较高,有时候代码改了,注释忘了同步修改,就会让代码阅读者更加迷惑。当然,如果代码中一行注释都没有,那只能说明这个程序员很懒,我们要适当督促一下,让他注意添加一些必要的注释。

按照我的经验来说,类和函数一定要写注释,而且要写得尽可能全面、详细,而函数内部的注释要相对少一些,一般都是靠好的命名、提炼函数、解释性变量、总结性注释来提高代码的可读性。

重点总结

好了,今天的内容到此就讲完了。我们来一块总结回顾一下,你需要掌握的重点内容。

关于注释

  • 注释的目的就是让代码更容易看懂。只要符合这个要求的内容,你就可以将它写到注释里。总结一下,注释的内容主要包含这样三个方面:做什么、为什么、怎么做。对于一些复杂的类和接口,我们可能还需要写明 “如何用”。
  • 注释本身有一定的维护成本,所以并非越多越好。类和函数一定要写注释,而且要写得尽可能全面、详细,而函数内部的注释要相对少一些,一般都是靠好的命名、提炼函数、解释性变量、总结性注释来提高代码可读性。

发表评论

您的电子邮箱地址不会被公开。 必填项已用*标注

关注我们