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

评论

  • VladilenGergo回复

    buy viagra in johor

    <a href=http://viagraomz.com/>generic viagra online</a>

    <a href="http://viagraomz.com/">buy viagra</a>

    afghanistan viagra post

  • Carlos Eduardo Veiga回复

    Every weekend i used to visit this web page, as i wish for enjoyment, for the reason that this this website conations genuinely good funny stuff too.|

  • MakritskayaGergo回复

    herbal viagra vitamin shoppe

    <a href=http://viagraoail.com/>generic viagra online</a>

    <a href="http://viagraoail.com/">buy generic viagra</a>

    generic viagra india price

  • gclub login回复

    I was suggested this website by my cousin. I am not sure whether this post is written by him as no one else know such detailed about my difficulty. You are wonderful! Thanks!

  • VladilenGergo回复

    lo que mejor viagra

    <a href=http://viagraomz.com/>viagra cheap</a>

    <a href="http://viagraomz.com/">viagra cheap</a>

    viagra presentaciones

  • adidas nmd回复

    I wish to voice my respect for your kindness for people who actually need assistance with this important concern. Your real dedication to getting the solution throughout had been exceedingly helpful and has surely allowed those just like me to achieve their aims. Your new warm and helpful help and advice entails a great deal to me and somewhat more to my colleagues. Best wishes; from all of us.

  • pradabagoutlet.net回复

    It is appropriate time to make some plans for the future and it is time to be happy. I have read this post and if I could I desire to suggest you few interesting things or tips. Perhaps you could write next articles referring to this article. I want to read even more things about it!

  • outdoor photograph回复

    I have been absent for a while, but now I remember why I used to love this website. Thank you, I¡¦ll try and check back more often. How frequently you update your web site?

  • Laboratorium回复

    This is very interesting, You are a very skilled blogger. I have joined your feed and look forward to seeking more of your great post. Also, I've shared your website in my social networks!

  • Homesearch回复

    Thanks , I have just been looking for information about this topic for a long time and yours is the greatest I have came upon so far. However, what about the bottom line? Are you certain concerning the supply?

  • air travel回复

    hello there and thank you for your info – I have definitely picked up something new from right here. I did however expertise several technical issues using this website, as I experienced to reload the website many times previous to I could get it to load properly. I had been wondering if your web host is OK? Not that I'm complaining, but slow loading instances times will sometimes affect your placement in google and can damage your high-quality score if ads and marketing with Adwords. Well I am adding this RSS to my e-mail and can look out for much more of your respective exciting content. Ensure that you update this again very soon..

  • Department Of Education回复

    I was just seeking this information for a while. After six hours of continuous Googleing, finally I got it in your site. I wonder what's the lack of Google strategy that do not rank this kind of informative web sites in top of the list. Normally the top websites are full of garbage.

  • michael jordan shoes回复

    There may be noticeably a bundle to know about this. I assume you made certain good factors in features also.

  • Diane回复

    I'm gone to inform my little brother, that
    he should also pay a quick visit this website on regular basis to take updated from most up-to-date
    information.

  • tercio borlenghi jr回复

    Thanks designed for sharing such a pleasant idea, article is fastidious, thats why i have read it fully|

  • AdamGergo回复

    generic cialis 5 mgm prices

    http://canadianiucialis.com/ - order cialis online

    <a href="http://canadianiucialis.com/">canadian cialis</a>

    kosten von cialis

  • video security回复

    This paragraph will assist the internet users for building up new
    blog or even a weblog from start to end.

  • Jose Wilame Araujo Rodrigues回复

    Does your blog have a contact page? I'm having problems locating it but, I'd like to send you an email. I've got some ideas for your blog you might be interested in hearing. Either way, great website and I look forward to seeing it grow over time.|

  • LenaGergo回复

    viagra funciona verdad

    <a href=http://norxcheapviagraf.com/>buy generic viagra</a>

    <a href="http://norxcheapviagraf.com/">cheap viagra</a>

    compro viagra en madrid

  • VladilenGergo回复

    viagra costs medco

    <a href=http://viagraomz.com/>cheap viagra</a>

    <a href="http://viagraomz.com/">buy viagra</a>

    viagra composition chimiqu

  • Nannik TV回复

    I really liked your blog article.Thanks Again. Keep writing.

  • wireless spy cam回复

    Hi I am so glad I found your blog, I really found you by mistake, while I was
    searching on Askjeeve for something else, Anyways I am here now and would just like to say thanks
    a lot for a incredible post and a all round thrilling
    blog (I also love the theme/design), I don't have time
    to look over it all at the moment but I have saved it and also included your RSS feeds,
    so when I have time I will be back to read more, Please do
    keep up the superb work.

  • TV Stands, Mounts & Furniture回复

    I enjoy you because of all your efforts on this blog. My aunt really likes managing research and it's easy to see why. My spouse and i hear all relating to the dynamic form you deliver efficient solutions through this website and in addition welcome response from other ones about this subject so my daughter is really studying a lot. Enjoy the remaining portion of the new year. You are doing a stunning job.

  • Shoes and Sandals回复

    I like the valuable information you provide in your articles. I will bookmark your weblog and check again here frequently. I'm quite sure I will learn many new stuff right here! Good luck for the next!

  • Tights, Socks & Hosiery回复

    Hiya, I'm really glad I have found this information. Today bloggers publish just about gossips and web and this is really frustrating. A good website with exciting content, that's what I need. Thanks for keeping this site, I'll be visiting it. Do you do newsletters? Cant find it.

  • Baby nursery home design回复

    You actually make it seem so easy together with your presentation however I in finding this matter to be actually something which I feel I might by no means understand. It sort of feels too complex and very vast for me. I am looking ahead for your next publish, I¡¦ll try to get the dangle of it!

  • Hair Removal skin care回复

    I get pleasure from, cause I discovered just what I used to be having a look for. You've ended my 4 day lengthy hunt! God Bless you man. Have a great day. Bye

  • Home Remodeling Advice回复

    Definitely believe that which you said. Your favorite justification appeared to be on the net the easiest thing to be aware of. I say to you, I definitely get irked while people consider worries that they just do not know about. You managed to hit the nail upon the top and defined out the whole thing without having side-effects , people could take a signal. Will probably be back to get more. Thanks

  • Hair Removal skin care回复

    I needed to draft you one very little observation to be able to say thank you again for all the marvelous solutions you've shown on this page. This is seriously generous with people like you to supply openly exactly what a few individuals could have distributed for an e book to generate some cash for their own end, primarily given that you could have done it if you wanted. These basics in addition worked to become a good way to be certain that other people online have similar desire just as my very own to know whole lot more with regards to this issue. I believe there are a lot more enjoyable periods ahead for people who take a look at your blog post.

  • AdamGergo回复

    cialis pagamento paypa

    http://canadianiucialis.com/ - cialis online

    <a href="http://canadianiucialis.com/">cialis cheap</a>

    cialis 20 mg erezione

  • Yaramaz TV回复

    Thanks again for the post.Much thanks again. Really Great.

  • for details回复

    It as hard to find well-informed people on this subject, however, you seem like you know what you are talking about! Thanks

  • Automotive回复

    I'm really impressed with your writing skills as well as with the layout on your weblog. Is this a paid theme or did you modify it yourself? Anyway keep up the excellent quality writing, it’s rare to see a great blog like this one today..

  • Happy Mother Parenting回复

    I'm still learning from you, while I'm trying to reach my goals. I definitely enjoy reading all that is written on your blog.Keep the information coming. I loved it!

  • Desktop Computer回复

    It¡¦s really a cool and helpful piece of info. I am satisfied that you just shared this useful information with us. Please keep us informed like this. Thank you for sharing.

  • Online Mindful Parenting Course回复

    I wish to express some appreciation to you just for rescuing me from this particular dilemma. Right after surfing throughout the world-wide-web and seeing opinions that were not beneficial, I assumed my life was over. Being alive without the presence of approaches to the problems you've resolved by way of your good guide is a critical case, as well as the ones which could have in a wrong way damaged my entire career if I hadn't encountered your website. Your natural talent and kindness in playing with a lot of things was important. I am not sure what I would've done if I had not come across such a step like this. I can at this moment look forward to my future. Thanks a lot very much for your high quality and results-oriented guide. I won't be reluctant to endorse your site to any person who needs to have guidance on this topic.

  • Dealership回复

    Of course, what a magnificent site and instructive posts, I will bookmark your website.Have an awsome day!

  • New Technology回复

    It¡¦s actually a great and helpful piece of info. I¡¦m glad that you simply shared this useful information with us. Please stay us informed like this. Thanks for sharing.

  • VladilenGergo回复

    liquide suisse viagra

    <a href=http://viagraomz.com/>buy viagra online</a>

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

    rezept viagra online

  • ultra boost回复

    I precisely needed to appreciate you once again. I am not sure what I would have tried in the absence of the type of creative ideas revealed by you concerning this problem. Entirely was an absolute fearsome dilemma in my circumstances, however , looking at a new expert fashion you treated that forced me to weep over fulfillment. I'm just thankful for this work and as well , believe you really know what an amazing job you are always undertaking training men and women all through your web site. I'm certain you haven't met all of us.

  • office movers回复

    Im obliged for the article post.Really looking forward to read more. Will read on

  • nike air max 2017回复

    You made some decent points there. I seemed on the internet for the issue and located most people will go together with together with your website.

  • Itamar Serp回复

    Good day! This post couldn't be written any better! Reading through this post reminds me of my good old room mate! He always kept chatting about this. I will forward this page to him. Pretty sure he will have a good read. Thanks for sharing!|