Java开发手册（四）：注释与异常处理

一、注释

1. 项目

项目建议提供注释，说明项目的作用，核心逻辑或需要注意的特别事项，方便其他人快速对项目形成整体了解。添加方式有两种：
1. 在根目录下创建README.md或README.txt
2. 在根目录下创建doc文件夹，在其创建README.md或README.txt，还可以在该目录下存储一些初始化语句、索引创建语句等内容

2. 包

说明该包的核心作用，注释可在package-info.java内设置，建议在核心包上有选择添加。

3. 类

所有类都需要添加注释，类注释采用javadoc规范的方式( /* / ),注释包括：该类的主要作用及使用时的一些注意事项、创建者和创建日期，可通过codetemplate来统一格式。

4. 类方法

类方法注释采用javadoc规范的方式( /* / )，注释包括：该方法的作用、使用注意事项、参数、返回值、抛出异常信息，可通过codetemplate来统一格式，添加注释时可以模仿jdk内方法的注释。

如果注释的工作量太大，对于私有方法，可以简化注释，做到能清晰说明其作用即可。但是所有的抽象方法(包括接口中的方法)的注释必须严格的按照javadoc规范进行添加，需要额外指出对子类的实现要求，或者调用注意事项。

当然也会有例外情况，如controller内使用swagger2提供在线文档，那就没必要再提供javadoc注释了。

5. 类属性

所有的类属性都需要添加注释，所有可用通过类名.属性、对象实例.属性调用的类属性都应该使用javadoc进行注释，如常量、枚举类型字段；POJO类的属性个人感觉使用行内注释会更合适一些，普通实例变量建议使用javadoc方式。

6. 方法内

方法内部单行注释，在被注释语句上方另起一行，使用//注释。方法内部多行注释使用/* */注释，注意与代码对齐。

可以这样记忆// 和 /* */只在方法内部和POJO内使用，其他时候都使用javadoc方式的注释。

7. 其他建议

1. 注释使用中文，专有名词与关键字保持英文原文即可。
2. 代码修改的同时，注释也要进行相应的修改。
3. 如果一段代码需要注释掉，在上方详细说明；如果代码已无用，直接删除更好。
4. TODO（待办事宜），FIXME（错误，不能工作）这类特殊注释标记，添加时留下添加人、时间、预计处理时间，并及时处理，不要写了就不管了。

对于注释的要求:第一、能够准确反应设计思想和代码逻辑;第二、能够描述业务含义，使别的程序员能够迅速了解到代码背后的信息。完全没有注释的大段代码对于阅读者形同天书，注释是给自己看的，即使隔很长时间，也能清晰理解当时的思路;注释也是给继任者看的，使其能够快速接替自己的工作。

额外的，好的命名、代码结构是自解释的，注释力求精简准确、表达到位。避免出现注释的一个极端:过多过滥的注释，代码的逻辑一旦修改，修改注释是相当大的负担。

二、异常处理

主要涉及什么情况下添加异常处理，捕获异常后的处理方式，finally内注意事项及其它几点建议。

1. 异常捕获

1. 不要捕获IndexOutOfBoundsException、NullPointerException等运行时异常，这类异常可以通过条件判断避免；也不要使用异常来做流程控制，异常的处理效率比条件分支低；
2. 不要对大段代码进行try-catch，只在可能发生异常且需要对异常处理的场景有针对性的进行try-catch捕获异常；

2. 异常处理

1. 捕获异常后严禁什么也不做或者直接e.printStackTrace()输出信息至控制台；如果不想处理，将该异常抛给上层，最外层的业务使用者，必须处理异常，将其转化为用户可以理解的内容；
2. 在代码中使用“抛异常”还是“返回错误码”，对于公司外的 http/api 开放接口必须 使用“错误码”;而应用内部推荐异常抛出;跨应用间 RPC 调用优先考虑使用 Result 方式，封 装 isSuccess()方法、“错误码”、“错误简短信息”。
3. 定义时区分unchecked/checked 异常，避免直接抛出newRuntimeException()， 更不允许抛出 Exception 或者 Throwable，应使用有业务含义的自定义异常。

3. finally使用

1. 在finally块中进行资源回收（关闭资源对象、流对象）时，有异常也要做try-catch
2. finally块中不能使用return，finally块中的Return返回后方法结束执行，不会执行try-catch块中的return语句；

4. 其它建议

1. 有 try 块放到了事务代码中，catch 异常后，如果需要回滚事务，一定要注意手动回 滚事务。
2. 防止 NPE，是程序员的基本修养，注意 NPE 产生的场景；