| Java中注释的规范&规则 | 您所在的位置：网站首页 › 代码注释的三种格式怎么写 › Java中注释的规范&规则 |
|
目录
为什么写注释？Java注释的方法有三种：Java注释具体使用细节：添加注释时的一点建议Javadoc注释标签语法：Java注释的使用顺序特别声明：
注释的抽取参考文档
Ps：按每段后的——可返回目录 为什么写注释？ 提高代码可读性；使程序条理清晰；方便后期代码维护；方便程序员间的交流沟通；生成帮助文档。—— Java注释的方法有三种： 单行注释： 单行注释，以//开头，//后的内容都是注释，直到这一行的行尾结束。多行注释： 以/*星号开头，以*/结束，可以有多行。可以使用多行注释作为行内注释，但多行注释不能嵌套使用。Javadoc注释： 以/**开头，以*/结束，如果有多行，每行通常以*开头 文档注释允许把关于程序的信息嵌入到程序内部，开发者可以用Javadoc工具提取这些信息，并把它们放在HTML文件中，形成帮助文档（后期写项目时，可以生成项目的API） 操作：/** + Enter—— Java注释具体使用细节：类、类属性、类方法接口 必须注释且使用Javadoc注释。需要标明，创建者，创建时间，版本，以及该类的作用。如下所示: package indi.mario.learn.demo; /*** @author: mario * @date: 19-07-08 * @version: 1.0.0 * @deion: 生成Jpg工具类 */ public class JpgUtils {} 原因： 在IDE编辑窗口中，Javadoc方式会提示相关注释，生成Javadoc可以正确输出相应注释：在IDE中，工程调用方法时，不进入方法即可悬浮提示方法、参数、返回值的意义，提高阅读效率。 方法 所有的抽象方法（包括接口中的方法）必须要用Javadoc注释、除了返回值、参数、异常说明外，还必须指出该方法做了什么事情，实现了什么功能。如下所示： /** * 生成Jpg文件 * @param htmlContent 待生成Jpg的 html内容 * @param file 生成Jpg文件地址 * @see JpgUtils#getFontPath() * @return true 生成成功 false 生成失败 */ public static boolean generateJpg(String htmlContent,File file){ … return result; } 说明：对子类的实现要求或者调用的注意事项，请一并说明。 方法内部单行注释，，在被注释语句上方另起一行，使用//注释。方法内容多行注释使用/* */注释，注意与代码对齐。 常量 对常量，我们需要使用多行注释，进行标明该常量的用途，如下所示: /*** @author: mario * @date: 19-07-08 * @version: 0.0.1 * @deion: */public class StatusConsts { /** * 博客地址 */ public static final String BLOG=“https://blog.csdn.net/InjoyMario”; } 关键算法 在关键算法上，添加注释并且按照顺序依次标明，写明白该方法为什么这么做。如下所示: /** * 应用场景: * 1. 在windows下,使用Thread.currentThread()获取路径时,出现空对象，导致不能使用 * 2. 在linux下,使用JpgUtils.class获取路径为null, * 获取字体路径 * @return 返回字体路径 */ private static String getFontPath(){ String path=""; // 1. ClassLoader classLoader= Thread.currentThread().getContextClassLoader(); URL url = (classLoader==null)?null:classLoader.getResource("/"); String threadCurrentPath = (url==null)?"":url.getPath(); // 2. 如果线程获取为null,则使用当前JpgUtils.class加载路径 if(threadCurrentPath==null||"".equals(threadCurrentPath)){ path = JpgUtils.class.getClass().getResource("/").getPath(); } // 3. 拼接字体路径 StringBuffer stringBuffer = new StringBuffer(path); stringBuffer.append("/fonts/SIMKAI.TTF"); path = stringBuffer.toString(); return path; } —— 添加注释时的一点建议 类中，接口等必须有创建时间、创建人、版本号、描述等注释。注释不是越多越好，比如：get/set方法就不需要写注释。更不需要每一行都写注释。注释需要写的简明易懂。特别是方法的参数，以及返回值。每一次修改时，相应的注释也应进行同步更新。在类，接口，方法中，应该都使用/** */Javadoc注释。因为这样调用者就不需要进入方法内部才知道方法的用处。提高编码效率。方法代码中如果有顺序之分，最好将代码也加上序号，如1，2，3等。所有的枚举类型字段都必须添加注释，说明每个数据项的用途。与其用半吊子英文解释，有的时候不如用中文注释说明清楚。代码如果修改时，注释也要相应修改，尤其是参数、返回值、异常、核心逻辑等的修改。谨慎注释掉代码。在上方详细说明，而不是简单地注释掉。如果不用，则删除。如果注释包含多段内容，段与段之间需要用分隔，空行是没用的为了避免一行过长影响阅读效果，务必将每行的长度限制在80个字符以内.使用 关键字 来强调关键字，建议强调的内容有：java关键字、包名、类名、方法名、接口名、字段名、参数名注释要求有二：1.要能反映设计思想和代码逻辑；2.能够描述业务含义好的命名、代码结构是自解释的。英文注释避免拉丁风格的缩写。比如使用also knwon as而不是aka， 使用that is或to be specific而不是i.e.，使用for example而不是e.g.，使用in other words或namely而不是viz.特殊注释标记：清注明标记人和标记时间。注意及时处理这些标记，通过标记扫描，经常清理这些标记。线上故障有时候就源于这些标记： （1）待办事宜（TODO）：（标记人，标记时间，[预计处理时间]） 表示需要实现，但目前还没有实现的功能。这实际上是一个Javadoc的标签。目前Javadoc还没有实现，但已经被广泛使用。只能应用于类，接口和方法（因为他是一个Javadoc标签） （2）错误，不能工作（FIXME）：（标记人，标记时间，[预计处理时间]） 在注释中用FIXME标记某代码是错误的，而且不能工作，需要及时纠正的情况。 —— Javadoc注释标签语法： 标签作用域说明@author文件、类、属性、方法标明开发该类模块的作者，多个作者使用多个@author标签标识，java doc中显示按输入时间顺序罗列。@version文件、类、方法标识注释对象的版本号@see类，属性，方法参考转向（相关主题）@param方法对方法中某参数的说明@return方法对方法返回值的说明@exception方法方法抛出的异常类型@throws方法方法抛出的异常类型说明@deprecated文件、类、方法说明对象过期，应该告诉用户这个API被哪个新方法替代了，随后用 @see 标记或 {@link} 标记指向新API@link类、方法链接到一个目标，用法类似@see，区别在于，@link标记能够嵌入到注释语句中，为注释语句中的特殊词汇生成连接。例如{@link …}@since JDK版本文件、类用于标识编译该文件所需要的JDK环境。 Java注释的使用顺序 @author (classes and interfaces only, required)@version (classes and interfaces only, required. See footnote 1)@param (methods and constructors only)@return (methods only)@exception (@throws is a synonym added in Javadoc 1.2)@see@since@serial (or @serialField or @serialData)@deprecated (see How and When To Deprecate APIs) 多个@author标记，应该按照时间顺序排列，即原作者应该排在第一个位置多个@param标记，应该按照参数定义的顺序排列多个@exception（或是@thrown）应该按照异常的字母顺序排列多个@see标记，应该按照注释的逻辑顺序排列，即从最近的到最远的，从最具体的到最一般的 特别声明： Javadoc针对public类生成注释文档标记部分跟在描述部分之后，且前面必须有一个空行间隔Javadoc只能在public、protected修饰的方法或者属性之上如果方法有参数，@param必须包含，而且每个对应一个参数 如果方法有返回值，@return必须包含Javadoc注释的格式化：前导*号和HTML标签Javadoc注释只负责描述类(class)、接口(interface)、方法(method)、构造器(constructor)、成员字段(field)。相应地，文档注释必须写在类、接口、方法、构造器、成员字段前面，而写在其他位置，比如函数内部，是无效的文档注释。如果源文件中有用到@version,@author标记，则在执行Javadoc命令时，要加-version -author javadoc -version -author -d doc *.java （其中用-version用于提取源文件中的版本信息 -author用于提取源文件中的作者信息）文档注释采用HTML语法规则书写，支持HTML标记(tag)，同时也有一些额外的辅助标记。需要注意的是，这些标记不是给人看的（通常他们的可读性也不好），他们的作用是为了javadoc工具更好地生成最终文档。—— @see: 注释中，为更好描述，需要引用和参考其他代码，为更好阅读体验，Javadoc支持链接跳转，需要用到@see 完整的用法： @see package.class#member 具体用法： 如果指向在当前类中，可以只写#号后面的如果指向在当前包中，可以省略包名如果指向在当前项目其它包中，需要指向全路径@link与@see的小区别： @see必须顶头写，而@link可以随意放，否则@see会失去效用。 —— 注释的抽取假设HTML文件将被存放在目录docDirectory下。执行以下步骤： 切换到包含想要生成文档的源文件目录。如果有嵌套的包要生成文档，例如com.horstmann.corejava，就必须切换到包含子目录com的目录(如果存在overview.html文件的话，这也是它所在目录)。 如果是一个包，应该运行命令： javadoc -d docDirectory nameOfPackage或对于多个包生成文档，则运行： javadoc -d docDirectory nameOfPackage1 nameOfpackage2...如果文件在默认包中，就应该运行： javadoc -d docDirectory *.java可以使用-link，用来为标准类添加超链接。例如： javadoc -link http://docs.oracle.com/javase/8/docs/api *.java那么，所有的标准类库类都会自动的链接到Oracle网站的文档。、 （这里参考了故克里的博文：Javadoc注释的生成规则） —— 参考文档官方文档：http://java.sun.com/j2se/1.3/docs/tooldocs/win32/javadoc.html 本文作者： InjoyMario 本文链接： https://blog.csdn.net/InjoyMario/article/details/95043728 版权声明： 本博客所有文章除特别声明外，均采用 ©BY-NC-SA 许可协议。转载请注明出处！ |
| CopyRight 2018-2019 实验室设备网 版权所有 |