当前位置：网站首页 > Java基础 > 正文

java注释基础

Java基础 来源： 网络 编辑：小编 发布时间：2024-10-23 11:18:03 浏览量：41



Java 注释

此文章已收录至项目 Developer-Knowledge-Base

有三种注释：单行注释，多行注释与文档注释

  1. 单行注释 ，最常用的注释其注释内容从 开始到本行结尾。
  2. 多行注释 从 开始直至第一个 出现都属于多行注释，但多行注释不能嵌套，多行注释也可以注释掉不需要的代码
  3. 文档注释 可以自动地生成文档，这种注释以 开始，以 结束
 

文档注释
 

Javadoc 维基百科
 

Java 文档注释可以用来自动地生成文档。在 JDK 中有个 javadoc 的工具，可以由源文件生成一个 HTML 文档。使用这种方式注释源文件的内容，显得很专业，并且可以随着源文件的保存而保存起来。也就是说，当修改源文件时，也可能对这个源代码的需求等一些注释性的文字进行修改，那么，这时候可以将源代码和文档一同保存，而不用再另外创建一个文档。
 

Javadoc 的第一行是类或方法的简短描述，之后是详细描述，因为所有的 Javadoc 都被视为 HTML，所以可以多个段落可以用 标签
 

类的 Javadoc
 

第一段：概要描述，通常用一句或者一段话简要描述该类的作用，以英文句号作为结束
 

第二段：详细描述，通常用一段或者多段话来详细描述该类的作用，一般每段话都以英文句号作为结束。详细描述一般用一段或者几个锻炼来详细描述类的作用，详细描述中可以使用 html 标签，如 、、、、 等标签，通常详细描述都以段落 p 标签开始。详细描述和概要描述中间通常有一个空行来分割
 

第三段：文档标注，用于标注作者、创建时间、参阅类等信息，还有泛型信息
 

 

方法的 Javadoc
 

写在方法上的文档标注一般分为三段：
 

第一段：概要描述，通常用一句或者一段话简要描述该方法的作用，以英文句号作为结束
 

第二段：详细描述，通常用一段或者多段话来详细描述该方法的作用，一般每段话都以英文句号作为结束
 

第三段：文档标注，用于标注参数、返回值、异常、参阅等
 

方法详细描述上经常使用 html 标签来，通常都以 p 标签开始，而且 p 标签通常都是单标签，不使用结束标签，其中使用最多的就是 p 标签和 pre 标签，ul 标签，i 标签。
 

pre 元素可定义预格式化的文本。被包围在 pre 元素中的文本通常会保留空格和换行符。而文本也会呈现为等宽字体，pre 标签的一个常见应用就是用来表示计算机的源代码。
 

 

 

变量的 Javadoc 注释
 

与方法类似的注释也可以用于变量的注释，只包含了对变量的简短描述
 

 

所有 Javadoc 标签
 


  标签&参数java注释基础用途适用于引入版本 
 @author 
 John Smith描述作者。可以是作者的名字也可以是指向作者的 a 标签等类、接口、枚举{ 
 @docRoot}表示从任何生成的页面生成的文档的根目录的相对路径。类、接口、枚举、成员、方法 
 @version 
 版本提供软件版本，每个类或接口最多一个。类、接口、枚举 
 @since 
 起始描述此功能首次存在的时间或者版本号。类、接口、枚举、成员、方法 
 @see 参考提供指向其他文档元素的链接。一般用于标记该类相关联的类类、接口、枚举、成员、方法 
 @param 
 名称 描述描述方法的一个参数。方法 
 @return 
 描述描述返回值。方法 
 @exception 
 类 描述 `` 
 @throws 
 类 描述描述可能从此方法抛出的异常。方法 
 @deprecated 描述描述一个过时的方法。类、接口、枚举、成员、方法{ 
 @inheritDoc}从被覆盖的方法复制描述。覆盖方法1.4.0{ 
 @link 
 参考}用于快速链接到相关代码类、接口、枚举、成员、方法{ 
 @linkplain 
 参考}与{@link}相同，但链接的标签以纯文本显示，而不是代码字体。类、接口、枚举、成员、方法{ 
 @value 
 #STATIC_FIELD}返回静态成员的值。静态成员1.4.0{ 
 @code 
 文本}在代码字体中格式化文字文本，等同于<code> {@literal} </code>。类、接口、枚举、成员、方法1.5.0{ 
 @literal 
 文本}表示文本，随附的文本被解释为不包含 HTML 标记或嵌套的 javadoc 标记。类、接口、枚举、成员、方法1.5.0{ 
 @serial 
 文本}在 Javadoc 注释中用于默认的可序列化字段。成员{ 
 @serialData 
 文本}记录 writeObject() 或 writeExternal() 方法写入的数据。成员、方法{ 
 @serialField 
 文本}记录 ObjectStreamField 组件。成员 

 

@link
 

 的使用语法 ，其中当包名在当前类中已经导入了包名可以省略，可以只是一个类名，也可以是仅仅是一个方法名，也可以是类名。方法名，使用此文档标记的类或者方法，可用通过按住 可以快速跳到相应的类或者方法上
 

示例
 

 

@code
 

{@code text} 会被解析成 
 

将文本标记为代码样式的文本，在 code 内部可以使用 < 、> 等不会被解释成 html 标签，code 标签有自己的样式
 

一般在 Javadoc 中只要涉及到类名或者方法名，都需要使用@code 进行标记。
 

@param
 

一般类中支持泛型时会通过@param 来解释泛型的类型
 

 

在方法上使用时后面跟参数名，再跟参数描述
 

 

@return
 

描述返回值信息
 

 

@throws
 

跟异常类型 异常描述 , 用于描述方法内部可能抛出的异常
 

 

@see
 

既可以用来类上也可以用在方法上，表示可以参考的类或者方法
 

 

@value
 

用于标注在常量上，{@value} 用于表示常量的值
 

 

注释的规范
 

原文：http://www.51gjie.com/java/109.html
 

注释形式统一
 

在整个应用程序中，使用具有一致的标点和结构的样式来构造注释。如果在其他项目组发现他们的注释规范与这份文档不同，按照他们的规范写代码，不要试图在既成的规范系统中引入新的规范。
 

注释的简洁
 

内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害。
 

注释的一致性
 

在写代码之前或者边写代码边写注释，因为以后很可能没有时间来这样做。另外，如果有机会复查已编写的代码，在今天看来很明显的东西六周以后或许就不明显了。通常描述性注释先于代码创建，解释性注释在开发过程中创建，提示性注释在代码完成之后创建。修改代码的同时修改相应的注释，以保证代码与注释的同步。
 

注释的位置
 

保证注释与其描述的代码相邻，即注释的就近原则。对代码的注释应放在其上方相邻或右方的位置，不可放在下方。避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释要对齐。
 

注释的数量
 

注释必不可少，但也不应过多，在实际的代码规范中，要求注释占程序代码的比例达到 20% 左右。注释是对代码的“提示”，而不是文档，程序中的注释不可喧宾夺主，注释太多了会让人眼花缭乱，注释的花样要少。不要被动的为写注释而写注释。
 

删除无用注释
 

在代码交付或部署发布之前，必须删掉临时的或无关的注释，以避免在日后的维护工作中产生混乱。
 

复杂的注释
 

如果需要用注释来解释复杂的代码，请检查此代码以确定是否应该重写它。尽一切可能不注释难以理解的代码，而应该重写它。尽管一般不应该为了使代码更简单便于使用而牺牲性能，但必须保持性能和可维护性之间的平衡。
 

多余的注释
 

描述程序功能和程序各组成部分相互关系的高级注释是最有用的，而逐行解释程序如何工作的低级注释则不利于读、写和修改，是不必要的，也是难以维护的。避免每行代码都使用注释。如果代码本来就是清楚、一目了然的则不加注释，避免多余的或不适当的注释出现。
 

必加的注释
 

典型算法必须有注释。在代码不明晰或不可移植处必须有注释。在代码修改处加上修改标识的注释。在循环和逻辑分支组成的代码中添加注释。为了防止问题反复出现，对错误修复和解决方法的代码使用注释，尤其是在团队环境中。
 


                            


                            

                                
  • 
                                    
                                    上一篇：
                                    
                                    java基础day06
                                    
                                    
                                
    • 
                                
  • 
                                    
                                    下一篇：
                                    
                                    java基础数据库详解
                                    
                                    
                                
    • 
                            
    

                            
                            
    
                                
    
                                    版权声明：
    
                                    本文来源网络，所有图片文章版权属于原作者，如有侵权，联系删除。

    
                                    
    本文网址：https://www.bianchenghao6.com/h6javajc/25292.html
    
                                
    
                            
    
                            
                        
    
                        
    
                            
    

                            
    
                        
    

                        
                        
                        
    
                            
    相关文章：
    
                            
                            
                        
                        
  • 
                                java基础day062024-10-23 11:18:03
                        
    • 
                        
                        
  • 
                                java中基础sql2024-10-23 11:18:03
                        
    • 
                        
                        
  • 
                                java16入门零基础2024-10-23 11:18:03
                        
    • 
                        
                        
  • 
                                java零基础免费班2024-10-23 11:18:03
                        
    • 
                        
                        
  • 
                                0基础学java找工作要多久2024-10-23 11:18:03
                        
    • 
                        
                        
  • 
                                java基础数据库详解2024-10-23 11:18:03
                        
    • 
                        
                        
  • 
                                零基础适合学java还是python2024-10-23 11:18:03
                        
    • 
                        
                        
  • 
                                Java基础飞机大战2024-10-23 11:18:03
                        
    • 
                        
                        
  • 
                                java学基础班都学2024-10-23 11:18:03
                        
    • 
                        
                        
  • 
                                java前端入门零基础2024-10-23 11:18:03
                        
    •