1、类注释
类的目的、即类所完成的功能,以及该类创建的时间和作者名称;多人一次编辑或修改同一个类时,应在作者名称处出现多人的名称;
/********************************************** Class name: 个人日常工作流程dwr服务 Description: Others: History: JC 2014.1.27 **********************************************/ @Controller public class DwrPersonalProcessService { ... }
2、方法注释
对于设置 (Set 方法 ) 与获取 (Get 方法 ) 成员的方法,在成员变量已有说明的情况下,可以不加注释;普通成员方法要求说明完成什么功能,参数含义是什么且返回值什么;另外方法的创建时间必须注释清楚,为将来的维护和阅读提供宝贵线索;
/** * 更新 HrmContract * @param context * @param request * @param hrmContract */ public ResultBean updateHrmContract(ServletContext context, HttpServletRequest request, HrmContract hrmContract ,String attach){ HrmContract tmp = hrmContractService.getHrmContractByPk(hrmContract.getPrimaryKey()); // 删除原附件 UtilTool.deleteAttachmentsNoFile(context, request, tmp.getContractFile()); // 保存附件 String ids = UtilTool.saveAttachments(context, request, attach); hrmContract.setContractFile(ids); String empid = UtilTool.getEmployeeId(request); hrmContract.initUpdate(empid); hrmContract.setCompanyId(UtilTool.getCompanyId(request)); hrmContractService.saveHrmContract(hrmContract); logger.info("更新 HrmContract..."); return WebUtilWork.WebResultPack(null); }
3、方法内部注释
控制结构,代码做了些什么以及为什么这样做,处理顺序等,特别是复杂的逻辑处理部分,要尽可能的给出详细的注释;
4、参数注释
参数含义、及其它任何约束或前提条件
5、中间变量注释
无特别意义的情况下不加注释;
6、注释格式
采用Eclipse默认的格式
采用完整的英文描述说明 JSP 所完成的功能,尽可能包括一个生动的动词;