Java开发手册(四):注释与异常处理

版权声明:本文为博主原创文章,未经博主允许不得转载。 https://blog.csdn.net/u014411966/article/details/78464900

一、注释

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 产生的场景;
阅读更多
想对作者说点什么?

博主推荐

换一批

没有更多推荐了,返回首页