锐客网

  1. 首页 > 生活百科 > it技术 > >

代码写注释的原则java java代码注释符号

IT技术注释

java工作中良好的代码注释习惯是什么注释是为了方便自己或代码维护方更容易地读懂代码代码写注释的原则java的用处 。
一、背景
1、当我们第一次接触某段代码代码写注释的原则java，但又被要求在极短代码写注释的原则java的时间内有效地分析这段代码，我们需要什么样的注释信息？
2、怎么样避免我们的注释冗长而且凌乱不堪呢？
3、在多人协同开发、维护的今天，我们需要怎么样的注释来保证高质、高交的进行开发和维护工作呢？
二、意义
程序中的注释是程序设计者与程序阅读者之间通信的重要手段 。应用注释规范对于软件本身和软件开发人员而言尤为重要 。并且在流行的敏捷开发思想中已经提出了将注释转为代码的概念 。好的注释规范可以尽可能的减少一个软件的维护成本 , 并且几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护 。好的注释规范可以改善软件的可读性，可以让开发人员尽快而彻底地理解新的代码 。好的注释规范可以最大限度的提高团队开发的合作效率 。长期的规范性编码还可以让开发人员养成良好的编码习惯，甚至锻炼出更加严谨的思维能力 。
三、注释的原则
1、 注释形式统一
在整个应用程序中，使用具有一致的标点和结构的样式来构造注释 。如果在其代码写注释的原则java他项目组发现他们的注释规范与这份文档不同 ， 按照他们的规范写代码，不要试图在既成的规范系统中引入新的规范 。
2、 注释的简洁
内容要简单、明了、含义准确，防止注释的多义性，错误的注释不但无益反而有害 。
3、 注释的一致性
在写代码之前或者边写代码边写注释 ， 因为以后很可能没有时间来这样做 。另外，如果有机会复查已编写的代码 ， 在今天看来很明显的东西六周以后或许就不明显了 。通常描述性注释先于代码创建，解释性注释在开发过程中创建 ， 提示性注释在代码完成之后创建 。修改代码的同时修改相应的注释，以保证代码与注释的同步 。
4、 注释的位置
保证注释与其描述的代码相邻，即注释的就近原则 。对代码的注释应放在其上方相邻或右方的位置 ， 不可放在下方 。避免在代码行的末尾添加注释；行尾注释使代码更难阅读 。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释要对齐 。
5、 注释的数量
注释必不可少，但也不应过多，在实际的代码规范中，要求注释占程序代码的比例达到20%左右 。注释是对代码的“提示”，而不是文档，程序中的注释不可喧宾夺主，注释太多了会让人眼花缭乱，注释的花样要少 。不要被动的为写注释而写注释 。
6、删除无用注释
在代码交付或部署发布之前，必须删掉临时的或无关的注释，以避免在日后的维护工作中产生混乱 。
7、 复杂的注释
如果需要用注释来解释复杂的代码 ， 请检查此代码以确定是否应该重写它 。尽一切可能不注释难以理解的代码，而应该重写它 。尽管一般不应该为了使代码更简单便于使用而牺牲性能，但必须保持性能和可维护性之间的平衡 。
8、 多余的注释
描述程序功能和程序各组成部分相互关系的高级注释是最有用的，而逐行解释程序如何工作的低级注释则不利于读、写和修改，是不必要的，也是难以维护的 。避免每行代码都使用注释 。如果代码本来就是清楚、一目了然的则不加注释，避免多余的或不适当的注释出现 。
9、必加的注释
典型算法必须有注释 。在代码不明晰或不可移植处必须有注释 。在代码修改处加上修改标识的注释 。在循环和逻辑分支组成的代码中添加注释 。为了防止问题反复出现，对错误修复和解决方法的代码使用注释，尤其是在团队环境中 。
10、注释在编译代码时会被忽略 ， 不编译到最后的可执行文件中 ， 所以注释不
会增加可执行文件的大小 。
四、JAVA注释技巧
1、空行和空白字符也是一种特殊注释 。利用缩进和空行，使代码与注释容易区
别，并协调美观 。
2、当代码比较长，特别是有多重嵌套时，为了使层次清晰，应当在一些段落的
结束处加注释（在闭合的右花括号后注释该闭合所对应的起点），注释不能
写得很长，只要能表示是哪个控制语句控制范围的结束即可 ， 这样便于阅读 。
3、将注释与注释分隔符用一个空格分开，在没有颜色提示的情况下查看注释时 ，
这样做会使注释很明显且容易被找到 。
4、不允许给块注释的周围加上外框 。这样看起来可能很漂亮 ， 但是难于维护 。
5、每行注释（连同代码）不要超过120个字(1024×768)，最好不要超过80
字(800×600)。
6、Java编辑器（IDE）注释快捷方式 。Ctrl / 注释当前行,再按则取消注释 。
7、对于多行代码的注释 ， 尽量不采用“/*......*/”，而采用多行“//”注释，
这样虽然麻烦，但是在做屏蔽调试时不用查找配对的“/*......*/” 。
8、注释作为代码切换开关，用于临时测试屏蔽某些代码 。
如何写好代码注释？对于代码注释来说，在不同的教程或者原则中有不同的规定或者解释 。有的原则是需要使用JavaDoc来描写每个方法 ， 而有的原则是要求每一个属性标注命名 。我愿意相信每一份看起来不那么妥当的注释都是出于一些善意的目的 ， 这就是注释的本质:
对未能自行解释的代码做出解释 。
在进行代码工作的时候我们多多少少会有一些陈旧的、与业务无关的逻辑在代码中运行 。有时候并不是一个变量名或者一个方法名就能阐述清楚产品同学所期望的业务内容 。我们希望将代码外的逻辑也加入到其中，但是一篇长篇大论的注释似乎也不那么妥当，所以对于注释我一般会加入一个约束的条件：
尽可能精简地描述当前方法、属性未能解释的逻辑 。
那么这个约束中的关键词是：精简、当前、未能解释 。这是我现在的理解 ， 如果有更好的见解也希望可以联系我进行沟通 。当然这些关键词在后文中也会进行解释 。
对于代码的退化这个概念在很多的领域之中都有阐述 。而一种比较主流的观点是：应用程序的生产寿命可能为3-5年 。当然这个大限将至无法使用的定义是有很大空间的 。但是这个说法的主要思想是：代码随着业务的迭代开发，会逐渐地降低可维护性 ， 直到它的生命终结 。代码是这样，对应的代码注释也是这样的 。
对于代码注释来说，不知道大家是否经历过类似的内容:
他们可能都是痛苦的回忆，但是这就是刚刚所描述的，注释的退化 。
对于代码来说，我们有许多的方法论、设计模式来尽可能地将代码的职责划分清晰从而延长 。而对于注释来说，我认为最大的方法是“不写注释”（关于这个在后面的章节中会再次讨论） 。
只要不写注释，注释就不会有问题 。之所以会有这个问题的原因是，通常人们在调整业务逻辑后无法完美地维护注释 。而更多情况是当代码逻辑发生变动了之后，注释直接编成了业务谜题中的一部分，开发人员不仅要在破败不堪的代码中梳理逻辑，还同时要小心错误注释发出的诱惑 。
同时，当代码发生退化逐渐变得不可控的时候，比起重新抽象代码结果，看起来以一段注释来描述新的逻辑比较简单 。但是带来的问题就是：“在尝试用注释弥补代码逻辑的问题” 。显然注释无法帮你抽象代码，只是看起来将问题爆发的时间延后了（甚至引入了更严重的问题） 。
那么“不写注释”的思想换一个角度来描述的话就是：让代码注释自己 。这是一种习惯 ， 举个最简单的例子:
可以改为:
哪怕是调整为:
可以看出来，第二种方法是指用对象内的方法，如果order只是一个自动生成的实体对象或者是一种值对象的话，那么也可以使用第三种方法 。
这样调整的好处就是，用代码自身去描述逻辑，从而尽量“不写注释” 。
对于不写注释的这个论点 ， 除了代码自动解释以外，还有很多情况下的注释都是不那么合适的 。
那么我对简单方法的定义是 ， 如果方法实际逻辑(刨除括号部分)5-7行（我自己的标准）则可以认为是一个简单方法 。读这样的方法的注释反而可能比直接看代码还来得复杂 。
对于一些无法直接用语言进行直接描述的逻辑 ， 我觉得要不就直接不要写注释了，让他们直接进行代码的阅读比较好 。否则有歧义性的注释反而会误导人员进行理解 。当然，对于我自己而言，内部项目中对于不便与用文字精确描述的逻辑，我会贴上wiki的连接进行图文描述 。这样对于不希望阅读的开发人员注释不会产生干扰，而同时图文配合又便于理解 。
JavaDoc标准要求对每个参数进行定义，但是这样带来的问题就是一些足够简明的参数的注释本身就是冗余的，例如:
尽管看起来很完美，但是它本身没有任何意义 。所以对于代码中具有自解释性的变量名称（它们本应该具有自解释性），JavaDoc的注释其实是非必要的 。
行为注释在在IDE里面行为的注释会导致代码的可读性大大降低，有的可能会在很长一段代码之后，有的则可能在很短的代码之后，他们的格式是不容易统一的，所以在现在广为流传的阿里巴巴开发手册中就明确的加上了在上一行中注释 。
事实上，我还在用用户署名，因为之前创建了文件模版之后就一直沿用了 。不过原则上来说，java文件署名的这个习惯是源于早期的代码版本控制并不是很发达的时代 。而现代版本控制中，文件的来世今生都由版本控制来进行了 ， 所以事到如今的用户署名已经没有意义了 。
注释掉的代码就应该直接删除 ， 否则会对后续的人员产生干扰 。人们可能会下意识地与注释掉的代码产生逻辑交互，并且认为这部分由其保留的目的而并不动 。和上条一样，在版本控制比较发达的今天，已经被注释的代码如果有其特殊的功能作用的话，应该是由一个单独的分支进行保护 ， 而非一段会干扰到正常业务开发的注释代码 。
如果注释所表达的功能与当前的方法无关的话，说明这部分的注释并不是完全为当前的方法服务的 。那么它就不应该出现在这里，也许在一个另外的readme或者是wiki文档中才是它更好的位置 。
如果将非当前功能的注释添加到方法上的话，那这里就会造成：如果要理解注释，就要去知道注释的上下文，那么这部分的注释本身就需要额外的说明，就与注释本身的功能背道而驰了 。
尽管我们希望不使用注释，直接让代码就能完成逻辑解释的功能，但有时候代码确实是无法完全胜任 。一般来说，以下的情况下是适用于进行注释补充的 。
有时候，对于额外的程序外的背景描述，是可以补充的 。这样可以在你尽管理解了代码逻辑，但是不知道他为什么这么实现的时候增加了额外的判断条件 。也可以帮你确认是由于什么考虑才成为了当前的代码逻辑，比如：
这样的话尽管你可能不认同之前人员实现的方法，但是至少可以知道他的目的，从而判断是否可以进行业务调整 。
代码是临时的在代码中进行的笔记 。尽管是注释，但却和单纯的代码注释的意义不一样 ， 可以进行标记 。但一定要记得定时的处理TODO，否则大家的敏感度会降低 。
警告如果业务或者功能方法在特定的情况下不应该执行 。这些情况往往是组合了一些业务情况的信息，或者是实际生产情况下产生bug的记录 。这样的注释将可以确实地提高解决问题的效率 。但是要注意的是这部分的内容可能会遭受到代码腐化的影响 。题外话：idea里面可以设置不同颜色的"@xxx"的标签 ， 例如我新建了"@ATTENTION"从而将后续的内容调整成了紫色以提供相应的警示作用 。
事实上，对于上面的观点很多观点，也是大多数全球程序员的观点 。而中国自有我大国之情：便是语言问题 。上文所说的代码自解释性的前提是对代码的表达意思了解得准确 。而会想一下你对一些领域模型进行起名的时候，有多少是通过谷歌翻译、或者百度结果而查出来的？对于这种得到的名词来说，很难定义它是准确地描述了开发人员意图的变量名称 。所以如果是这种前提的话 ， 我认为对于指定对象中的字段、或者指定使用的参数、局部变量等名称，是可以酌情在属性、方法名上对指定的名字进行约束解释 ， 以便由于方法名称和其他的概念混淆 。简单点来说：
对于没有信心使用英文精准描述的名称，还是用注释进行约束较好 。
本文主要内容来自《Clean Code》中注释一章 。阅读感悟主要是文章中的内容有一些是针对超长工作经验的老油条说的，他们可能由于过往的习惯导致注释问题，而这一点在中国互联网存在的问题不明显；中国的母语区别导致代码的自解释性降低，学好英语还是非常重要的呀 。
代码设计时应遵循哪些原则1提高编码质量代码写注释的原则java，代码可读性和可维护性 。
2代码编写规范
2.1删除所有无用代码
2.2必须给代码添加注释，一个类代码写注释的原则java的注释字数不得小于代码的百分之20%
2.3建议遵循30秒原则 。如果另一个程序员无法在三十秒内无法知道你的函数在做什么，如何做以及为什么要这样做，那么说明你的代码是难于维护的，需要得到提高 。
2.4一个函数的代码长度不允许超过100行，超过一百行的函数建议在不破坏原子性的基础上进行拆分 。
2.5变量都应在方法或者类的头部集中定义
2.6保证一行代码只做一件事
2.7使用括号来控制操作符的运算顺序，以免使用java默认的操作符优先级顺序 。
2.8代码格式化：对代码进行格式化，再进行提交 。
2.9接口不允许没有方法或者变量的声明
3.命名规范
3.1各种标识符的命名要使用有实际意义的英文单词或者英文单词缩写，缩写词及英文单词要收录在项目的简写词汇表中 。切忌使用阿拉伯数字和拼音进行命名 。
3.2类名：首字母大写 ， 每个单词首字母都需要大写 。
3.3方法名：首字母小写，其余单词首字母都需大写 。
3.4全局变量，和常量名称要求全部字母大写 。
3.5参数名称与局部变量基本相同，区别在于参数名称需要加上冠词a ，an 或者在单词结尾以s结束 。
4.注释规范
4.1注释需要注意的事项：

    推荐阅读


    上一篇：sqlserver连表分组查询语句，sql语句连接表

    下一篇：java美国时区代码，java calendar 时区