Java注释示例一.docx

Java注释示例一关键字：Java 程序设计 注释 示例 技巧 原则序言世界级软件大师Kent Beck(大名鼎鼎的JUnit作者)在其著作Implementation Patterns中指出”Programs are read more often than they are written.”大意是“代码被阅读的时间远比写出来的时间要多得多”。好的注释能够帮助代码阅读者了解设计者思路，便于代码的维护和扩展。以下示例是从一些开源框架中摘录的代码片段，供有志于编写可阅读代码的开发人员参考。1. 解释为什么，而非是什么以下代码解释了月份减一和加一的原因，非常简洁明了。public int getMonth() return normalize().getMonth() - 1; / adjust 1-based to 0-based public void setMonth(int month) int y = 0;if (month = 12) y = month / 12; month %= 12; else if (month 0) y = CalendarUtils.floorDivide(month, 12); month = CalendarUtils.mod(month, 12); BaseCalendar.Date d = getCalendarDate();if (y != 0) d.setNormalizedYear(d.getNormalizedYear() + y);d.setMonth(month + 1); / adjust 0-based to 1-based month numbering2. 增强变量含义说明以下代码对变量doc作了增强说明，该注释表明代码是将文档是从2.0版本转换为3.0版本。/ Convert from 2.0 to 3.0 PDLDocument doc30 = convert(doc);3. 给代码划分段落如果一个方法的实现比较复杂，可以通过注释分段解释功能。如以下代码分为三个阶段，一个阶段用一段注释加以阐述。通常更好的做法是将一个复杂的方法重构为多个功能明确的方法。public void execute(ExecutionContext executionContext) Token token = executionContext.getToken(); / phase one: collect all the transitionNames Collection transitionNames = null; List forkedTokens = new ArrayList(); / by default, the fork spawns a token for each leaving transition if (script=null) transitionNames = getLeavingTransitionsMap().keySet(); else / a script is specified / if a script is specified, use that script to calculate the set / of leaving transitions to be used for forking tokens. Map outputMap = null; try outputMap = script.eval(token); catch (Exception e) this.raiseException(e, executionContext); if (outputMap.size()=1) Object result = outputMap.values().iterator().next(); if (result instanceof Collection) transitionNames = (Collection) result; if (transitionNames=null) throw new JbpmException(script for fork +name+ should produce one collection (in one writable variable): +transitionNames); / phase two: create forked tokens for the collected transition names Iterator iter = transitionNames.iterator(); while (iter.hasNext() String transitionName = (String) iter.next(); forkedTokens.add(createForkedToken(token, transitionName); / phase three: launch child tokens from the fork over the given transitions iter = forkedTokens.iterator(); while( iter.hasNext() ) ForkedToken forkedToken = (ForkedToken) iter.next(); Token childToken = forkedToken.token; String leavingTransitionName = forkedToken.leavingTransitionName; ExecutionContext childExecutionContext = new ExecutionContext(childToken); if (leavingTransitionName!=null) leave(childExecutionContext, leavingTransitionName); else leave(childExecutionContext); 4. 说明特殊的异常处理以下代码中注释解释了异常处理。try Class nodeClass = ClassLoaderUtil.getClassLoader().loadClass(className); types.put(elementTag, nodeClass); catch (Exception exception) / NOTE that Errors are not caught because that might halt the JVM and mask the original Error.if (!org.jboss.seam.jbpm.Page.equals(className) log.debug(node +elementTag+ will not be available. class +className+ couldnt be loaded); 5. 解释边界条件和操作布尔变量通常边界条件和操作布尔变量比较难以理解，增加注释可以使代码一目了然。 public void removeTaskInstanceSynchronization(Token token) TaskMgmtInstance tmi = getTaskMgmtInstance(token); Collection taskInstances = tmi.getTaskInstances(); if (taskInstances!=null) Iterator iter = taskInstances.iterator(); while (iter.hasNext() TaskInstance taskInstance = (TaskInstance) iter.next(); if (token.equals(taskInstance.getToken() / remove signalling if (taskInstance.isSignalling() taskInstance.setSignalling(false); / remove blocking if (taskInstance.isBlocking() taskInstance.setBlocking(false); / if this is a