Java语言编程规范——注释规范

一般情况下,源程序有效注释量必须在30%以上。注释的原则是有助于对程序的阅读理解,在该加的地方都加了,注释不宜太多也不能太少,注释语言必须准确、易懂、简洁。可以用注释统计工具来统计。
- 类和接口的注释:类和接口必须写注释。该注释放在 package 关键字之后,class 或者 interface 关键字之前。
说明:方便JavaDoc收集。
示例:

package com.huawei.msg.relay.comm;
/**
 * 注释内容
 */
public class CommManager
  • 类和接口的注释内容:类的注释主要是一句话功能简述、功能详细描述。
    格式:
/**
 * 〈一句话功能简述〉
 * 〈功能详细描述〉
*/

说明:描述部分说明该类或者接口的功能、作用、使用方法和注意事项。
示例:

/**
 * LogManager 类集中控制对日志读写的操作。
 * 全部为静态变量和静态方法,对外提供统一接口。分配对应日志类型的读写器,
 * 读取或写入符合条件的日志纪录。
*/
  • 必须写注释。geter、seter方法不用写注释。写在类属性、公有和保护方法上面。
    示例:
/**
 * 注释内容
 */
private String logType;
/**
 * 注释内容
 */
public void write()
  • 成员变量注释内容:成员变量的意义、目的、功能,可能被用到的地方。
  • 公有和保护方法注释内容:列出方法的一句话功能简述、功能详细描述、输入参数、输出参数、返回值、违例等。
    格式:
/**
 * 〈一句话功能简述〉
 * 〈功能详细描述〉
 * @param  [参数1] [in或out]  [参数1说明]
 * @param  [参数2] [in或out]  [参数2说明]
 * @return [返回类型说明]
 * @exception/throws [违例类型] [违例说明]
*/

说明: @exception或throws 列出可能仍出的异常;。
示例:

/**
 * 用MD5算法计算输入字符串的32位摘要
 * @param sIn [in] 待处理的字符串
 * @param sOut [out] sIn的32为摘要,调用函数负责new sOut对象
 * @return boolean
 */
public static boolean getMd5(String sIn, StringBuffer sOut) 
  • 注释应与其描述的代码相近,对代码的注释应放在其上方或右方(对单条语句的注释)相邻位置,不可放在下面,如放于上方则需与其上面的代码用空行隔开。
  • 注释与所描述内容进行同样的缩排。
    说明:可使程序排版整齐,并方便注释的阅读与理解。
    示例:如下例子,排版不整齐,阅读稍感不方便。
public void example( )
{
// 注释
     CodeBlock One

          // 注释
     CodeBlock Two
}

应改为如下布局。

public void example( )
{
     // 注释
     CodeBlock One

     // 注释 
     CodeBlock Two
}
  • 将注释与其上面的代码用空行隔开。
    示例:如下例子,显得代码过于紧凑。
//注释
program code one
//注释
program code two

应如下书写:

//注释
program code one
(空一格)   
//注释
program code two
  • 对变量的定义和分支语句(条件分支、循环语句等)对复杂的分支必须编写注释,如果时间允许,建议对所有分支语句写注释。
    说明:这些语句往往是程序实现某一特定功能的关键,对于维护人员来说,良好的注释帮助更好的理解程序,有时甚至优于看设计文档。

  • 对于switch语句下的case语句,如果因为特殊情况需要处理完一个case后进入下一个case处理,必须在该case语句处理完、下一个case语句前加上明确的注释。
    说明:这样比较清楚程序编写者的意图,有效防止无故遗漏break语句。

  • 边写代码边注释,修改代码同时修改相应的注释,以保证注释与代码的一致性。不再有用的注释要删除。

  • 注释的内容要清楚、明了,含义准确,防止注释二义性。
    说明:错误的注释不但无益反而有害。

  • 避免在注释中使用缩写,特别是不常用缩写。
    说明:在使用缩写时或之前,应对缩写进行必要的说明。

  • 用中文写注释,禁止用英文写注释。

####建议
- 避免在一行代码或表达式的中间插入注释。
说明:除非必要,不应在代码或表达中间插入注释,否则容易使代码可理解性变差。

  • 通过对函数或过程、变量、结构等正确的命名以及合理地组织代码的结构,使代码成为自注释的。
    说明:清晰准确的函数、变量等的命名,可增加代码可读性,并减少不必要的注释。

  • 在代码的功能、意图层次上进行注释,提供有用、额外的信息。
    说明:注释的目的是解释代码的目的、功能和采用的方法,提供代码以外的信息,帮助读者理解代码,防止没必要的重复注释信息。
    示例:如下注释意义不大。

// 如果 receiveFlag 为真
if (receiveFlag)

而如下的注释则给出了额外有用的信息。

// 如果从连结收到消息 
if (receiveFlag)
  • 在程序块的结束行右方加注释标记,以表明某程序块的结束。
    说明:当代码段较长,特别是多重嵌套时,这样做可以使代码更清晰,更便于阅读。
    示例:参见如下例子。
if (...)
{
    program code1
    while (index < MAX_INDEX)
    {
        program code2
    } // end of while (index < MAX_INDEX) // 指明该条while语句结束
} // end of  if (...) // 指明是哪条if语句结束
  • 方法内的单行注释使用 //。
    说明:调试程序的时候可以方便的使用 /* 。。。*/ 注释掉一长段程序。

  • 注释使用中文注释和中文标点,不得用英文写注释。方法和类描述的第一句话尽量使用简洁明了的话概括一下功能,然后加以句号。接下来的部分可以详细描述。
    说明:JavaDoc工具收集简介的时候使用选取第一句话。

  • 顺序实现流程的说明使用1、2、3、4在每个实现步骤部分的代码前面进行注释。
    示例:如下是对设置属性的流程注释

//1、 判断输入参数是否有效。
...
// 2、设置本地变量。
...
  • 一些复杂的代码需要说明。
    示例:这里主要是对闰年算法的说明。
//1. 如果能被4整除,是闰年;
//2. 如果能被100整除,不是闰年.;
//3. 如果能被400整除,是闰年.。

本文作者:Rance935本文出处:Java语言编程规范——注释规范转载请在开头注明作者详细信息和本文出处
欢迎关注我的微信公众号和QQ群,分享Android 开发和互联网内容
Android技术分享:群号534813930
微信号:androidparks
公众号:AndroidParks

评论

  • arts and photography回复

    Fantastic beat ! I would like to apprentice while you amend your website, how can i subscribe for a blog website? The account helped me a acceptable deal. I had been a little bit acquainted of this your broadcast provided bright clear concept

  • Home Flooring回复

    Wow, superb weblog structure! How lengthy have you ever been blogging for? you make blogging glance easy. The whole look of your web site is excellent, let alone the content material!

  • Growing With Plants回复

    My brother suggested I might like this website. He was entirely right. This post actually made my day. You can not imagine just how much time I had spent for this info! Thanks!

  • Continuing Education回复

    of course like your website but you need to test the spelling on several of your posts. Several of them are rife with spelling issues and I find it very bothersome to inform the reality then again I¡¦ll definitely come back again.

  • Just Bingo Sites回复

    Typewriter.. or.. UROPYOURETER. meaning аАа’аАТ‚аЂТ˜a collection of urine and pus within the ureter. a

  • Luiz Gastao Bittencourt da Silva回复

    Woah! I'm really enjoying the template/theme of this blog. It's simple, yet effective. A lot of times it's difficult to get that "perfect balance" between superb usability and appearance. I must say that you've done a great job with this. Also, the blog loads very fast for me on Internet explorer. Outstanding Blog!|

  • CheplanovaGergo回复

    viagra in costa rica

    http://viagralms.com/ - cheap viagra

    <a href="http://viagralms.com/">viagra online</a>

    viagra drug patent expiration

  • for more information回复

    safe power leveling and gold I feel pretty lucky to have used your entire website page and look forward to many more excellent times reading here