• 这些简单而容易忽视的细节却是你写出高质量代码不可或缺的东西
  • 李键 发表于 2016/3/14 21:41:00 | 分类标签: 代码重构 代码规范 书写规范
  • 现在java的出产地sun公司并没有定义一个java注释规范,注释规范目前是每个公司自己有自己的一套规范,主要是为了团队之间的协作。
     
    1、基本规则
     
         1.注释应该使代码更加清晰易懂
         2.注释要简洁明了,只要提供能够明确理解程序必要的信息就可以了。如果注释太复杂会影响程序整洁度和阅读感。
         3.注释不仅描述程序作了什么,还要描述为什么这样做以及约束。
         4.对于一般的getter和setter方法不用注释。
         5.类、接口、构造函数、方法、全局变量必须添加注释。字段属性可以选择添加简单注释。
         6.简单注释一般不超过10个字。
         7.特殊地方必须要添加注释。比如一下几个地方:典型算法,代码不明晰处,在代码修改处,在循环和逻辑分支组成代码处,为他人提供的接口。
     
    2、三种注释方式
     
         1.单行注释(single-line)://注释内容
          一次只能注释一行,一般是简单注释,用来简短描述某个变量或属性,程序块。
         2.块注释(block):/*注释内容*/
         为了进行多行简单注释,一般不使用。
         3.文档注释:/**注释内容 */
         可以使用多行,一般用来对类、接口、成员方法、成员变量、静态字段、静态方法、常量进行说明。Javadoc可以用它来产生代码的文档。为了可读性,可以有缩进和格式控制。
     
         文档注释常采用一些Javadoc标签进行文档的特定用途描述,用于帮助Javadoc产生文档,常用的有:
     
    标签用途说明
    @author name类/接口描述代码的作者,每个作者对应一个标签。
    @Description类/接口/方法对类,方法,接口的简单描述
    @deprecated类/成员方法说明该API已经废除。
    @exception name description 或 @throws name description成员方法描述方法抛出的异常,每一个异常对应一个标签
    @param name description成员方法描述成员方法中参数用途和意义,一个参数对应一个标签
    @return description成员方法描述成员方法的返回值的意义
    @since类/接口/成员方法描述该API最初出现时间,可以填写版本号
    @see ClassName类/接口/成员方法/成员变量用于引用特定的类的成员方法的描述,参考转向,一般ClassName是包括包名的全名
    @data类/接口/方法用于显示类,方法,接口具体创建时间,或者修改时间
    @version text类/接口版本
    @inheritDoc类/接口/成员方法继承的文档
    {@link address} 或者 @ linkplain address text}类/接口/方法用于创建一个指向另一份文档的超链接
     
    3、实例
     
         1.文件注释
         一般作比较详细描述,而且在同个项目里面统一使用,主要包括:版权声明,license许可证描述。
     
         示例(来自 spring-framework):
     
      /*
      * Copyright 2002-2016 the original author or authors.
      *
      * Licensed under the Apache License, Version 2.0 (the "License");
      * you may not use this file except in compliance with the License.
      * You may obtain a copy of the License at
      *
      * http://www.apache.org/licenses/LICENSE-2.0
      *
      * Unless required by applicable law or agreed to in writing, software
      * distributed under the License is distributed on an "AS IS" BASIS,
      * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
      * See the License for the specific language governing permissions and
      * limitations under the License.
      */
     
         2.类/接口注释
     
         类,接口描述,一般作详细描述。按照常用的说明顺序呢排列,主要包括
              1.类的描述,以。或.结束。
              2.类设计的目标,完成什么样的功能一般和类的描述合并在一起。
              3.<Strong>主要的类使用</Strong>如何使用该类,包括环境要求,比如线程是否安全,并发性要求以及使用约束。
              4.<Strong>已知的BUG</Strong>
              5.描述类的修改历史:<Strong>修改人+日期+简单说明</Strong>
              6.@author作者、@version版本,@see参照,@since开始版本信息
         示例(来自spring-framework):
     
       /**
      * Delegate for resolving constructors and factory methods.
      * Performs constructor resolution through argument matching.
      *
      * @author Juergen Hoeller
      * @author Rob Harrop
      * @author Mark Fisher
      * @author Costin Leau
      * @since 2.0
      * @see #autowireConstructor
      * @see #instantiateUsingFactoryMethod
      * @see AbstractAutowireCapableBeanFactory
      */
     
         3.方法注释
     
         方法描述说明,主要对方法的描述,参数、返回值、抛出异常进行说明。
         示例(来自spring-framework)
     
          /**
      * Resolve the factory method in the specified bean definition, if possible.
      * {@link RootBeanDefinition#getResolvedFactoryMethod()} can be checked for the result.
      * @param mbd the bean definition to check 
      * @return a BeanWrapper for the new instance 
      * @throws Exception in case of any kind of processing failure
      */
     
         4.修改注释
     
         在修改处一定要添加注释,说明修改人,修改原因,修改内容,修改时间
  • 请您注意

    ·自觉遵守:爱国、守法、自律、真实、文明的原则

    ·尊重网上道德,遵守《全国人大常委会关于维护互联网安全的决定》及中华人民共和国其他各项有关法律法规

    ·严禁发表危害国家安全,破坏民族团结、国家宗教政策和社会稳定,含侮辱、诽谤、教唆、淫秽等内容的作品

    ·承担一切因您的行为而直接或间接导致的民事或刑事法律责任

    ·您在编程中国社区新闻评论发表的作品,本网站有权在网站内保留、转载、引用或者删除

    ·参与本评论即表明您已经阅读并接受上述条款

  • 感谢本文作者
  • 作者头像
  • 昵称:李键
  • 加入时间:2013/5/16 0:00:00
  • TA的签名
  • 这家伙很懒,虾米都没写
  • +进入TA的空间
  • 以下内容也很赞哦
分享按钮