Java/Android 开发中如何正确使用注释

April 1, 2016

技术管理

一般来说,被注释的代码或者内容是不被电脑执行的,电脑会跳过这些被注释的部分。看上去被注释的内容好像没有存在的意义,但是基本上,每个计算机语言都有注释这东西。Android/Java 中有三种注释方式。

首先是单行注释这个很常见。

// 这是单行注释

然后有两个多行注释

/*
*   这是多行注释
*/

/**
*   这也是多行注释
*/

其中,第一种多行注释只是简单的多行注释,而第二种多行注释一般用来生成 JavaDoc 文档。今天写这篇博客其实想说的是,虽然注释很简单,但是注释还是有很多讲究的。

我认为,注释有三种功能。

  1. 注释代码,注释掉不希望运行的代码,而又不想直接删除它们,这个在开发和调试中经常用到
  2. 给代码添加说明文档,这是注释的一个重要的功能。对于代码需不需要注释有很多讨论,咱们这里不讨论这个,只讨论注释这个功能。
  3. 生成 JavaDoc,平时开发中很少碰见,一般只有做 sdk 的开发者会需要。

常见的不规范的注释使用方式

在平时的工作过程中,经常能见到几种我认为不是很规范的注释方式。这些注释方式虽然不会引起什么麻烦,或者说不会引起什么 bug,但是我们确实可以做得更好。

第一种是使用 /* */ 进行多行注释

看看下面这个截图,这是很多人喜欢用的多行注释。

QQ图片20160401173503.png

只需要更改两行代码,就可以注释掉很多代码,看上去很爽,但其实不是这样的。写代码的人在自己的 IDE 上能很清晰的看出代码的修改,至少被注释的代码颜色跟其他的不一样。但是这个代码提交后呢,别人更新代码后,查看代码变更的时候,看到可能是这样的:

QQ图片20160401173537.png

或者你修改完代码,给别人发 patch 的时候,patch 的内容会是这样的:

QQ图片20160405110232.png

别人看到的是代码的片段,看不见被注释的代码的具体的内容,特别是注释的结尾,你只能看到花括号了。大家根本无法在这样的 patch 中看出被注释的代码具体是干什么的,只能回到源码里去查看。这样无疑增加了一些没必要的消耗。

所以,我个人认为,多行注释,还是使用 // 的方式,这样被注释的每一行都能被添加到变更记录中。比如下图中,别人很清楚可以看出所有的变动。

QQ图片20160405111721.png

第二种是在一行代码中夹杂 /* */ 注释

这样的注释让代码看上去更加难以阅读,我知道很多人为啥这样注释,完全是因为 IDE 的快捷键。首先,我是很反对在一行中进行多个变量的声明的,下图中是 Android 项目中,使用 butterknife 框架后,常见的一种代码书写方式,这种方式在开发的初期看上去能提高开发效率,但是随着项目的持续维护,这样的代码其实并不好。我个人对 butterknife 偏见也很大程度上是因为它提高了开发者效率,却没有很好的办法约束开发者写出漂亮的代码,当然,这本不应该是它的错。

QQ图片20160405110939.png

还有另外一种常见的,就是注释方法的参数列表。有些方法的参数列表本来就很长了,再加上这样的方式注释掉几个参数,这个方法会变得更长,如果在两个被注释掉的参数中,再夹一个有效的参数,这样让别人看起来更加头疼。

QQ图片20160405113428.png

第三种是使用 /***********/ 来分割代码

有些人喜欢在代码中使用这样的注释方式来分割代码,这样让一些代码看上去是一起的,相关的。看上去没什么问题,但是这样的注释一般会被识别为 /** */ ,然后就被认为是该注释下文最近一成员的注释,比如这样:

QQ图片20160405110525.png

第四种是在方法体中使用 /** */ 多行注释。

/** */ 是用来注释属性,方法,类等,用来生成 JavaDoc ,并且一般 IDE 会编程的过程中,根据这些注释进行提示。 比如下图的注释,为啥不可以使用 // 来注释呢?
QQ图片20160405111431.png

--- EOF ---

添加新评论