认识达内从这里开始

大家在阅读其他程序员的代码的时候会因为没有注释而感觉到理解难度被提高了很多吗?今天我们就通过案例分析来简单了解一下，Java编程注释的用法与格式分析。

注释是一个看起来简单，容易被忽视，但是作用又不容小觑的话题。好的注释能起到指路明灯、拨云见日、警示等作用，具体包括∶能够准确反映设计思想和代码逻辑;能够描述业务含义，使其他工程师能迅速了解背景知识。与代码不同，注释没有语法的限制，完全取决于编写者的能力和发挥，但这并不意味着注释可以天马行空。书写注释要满足优雅注释三要素。

Nothingisstrange

完全没有注释的大段代码对于阅读者来说形同天书。注释是给自己看的，即使离写完代码很长时间，也能清晰地理解当时的思路;注释也是给维护者看的，使其能够快速理解代码逻辑。

相信大多数人阅读JDK源码时都十分吃力，比如并发控制、集合算法等，这些天才级的程序基本上没有任何注释。JDK的代码稳定、高效压倒一切，不会朝编夕改。但是业务代码需要被不断地维护更新，没有注释的代码给人一种陌生感。世界上遥远的距离是，我和要修改的代码间缺少一段注释。因此，我们提倡要写注释，然后才是把注释写得精简。

Lessismore

从代码可读性及维护成本方面来讲，代码中的注释一定是精华中的精华。先，真正好的代码是自解释的，准确的变量命名加上合理的代码逻辑，无须过多的文字说明就足以让其他工程师理解代码的功能。如果代码需要大量的注释来说明解释，那么工程师应该思考是否可以优化代码表现力。

其次，泛滥的注释不但不能帮助工程师理解代码，而且会影响代码的可读性，甚至会增加程序的维护成本。如下示例代码是滥用注释的样例，方法名put，加上两个有意义的变量名elephant和fridge，已经明确表达了代码功能，完全不需要额外的注释。在遇到修改代码逻辑时，注释泛滥会带来灾难性的负担。

与时俱进的重要性对于开发工程师来说是不言而喻的。就像道路状况与导航软件一样，如果导航软件严重滞后，就失去了导航的意义。同样，针对一段有注释的代码，如果程序员修改了代码逻辑，但是没有修改注释，就会导致注释无法跟随代码前进的脚步，误导后续开发者。因此，任何对代码的修改，都应该同时修改注释。

注释格式

注释格式主要分为两种∶一种是Javadoc规范，另一种是简单注释。

Javadoc规范

类、类属性和类方法的注释必须遵循Javadoc规范，使用文档注释(/***/)的格式。按Javadoc规范编写的注释，可以生成规范的JavaAPI文档，为外部用户提供非常有效的文档支持。而且在使用IDE工具编码时，IDE会自动提示所用到的类、方法等注释，提高了编码的效率。

这里要特别强调对枚举的注释是必需的。有人觉得枚举通常带了Stringname属性，已经简要地说明了这个枚举属性值的意思，此时注释是多余的。其实不然，因为∶

(1)枚举实在太特殊了。它的代码极为稳定。如果它的定义和使用出现错误，通常影响较大。

(2)注释的内容不仅限于解释属性值的含义，还可以包括注意事项、业务逻辑。如果在原有枚举类上新增或修改一个属性值，还需要加上创建和修改时间，让使用者零成本地知道这个枚举类的所有意图。

(3)枚举类的删除或者修改都存在很大的风险。不可直接删除过时属性，需要标注为过时，同时注释说明过时的逻辑考虑和业务背景。

简单注释

包括单行注释和多行注释。特别强调此类注释不允许写在代码后方，必须写在代码上方，这是为了避免注释的参差不齐，导致代码版式混乱。双画线注释往往使用在方法内部，此时的注释是提供给程序开发者、维护者和关注方法细节的调用者查看的。因此，注释的作用更应该是画龙点睛的，通常添加在非常必要的地方，例如复杂算法或需要警示的特殊业务场景等。

【免责声明】：本内容转载于网络，转载目的在于传递信息。文章内容为作者个人意见，本平台对文中陈述、观点保持中立，不对所包含内容的准确性、可靠性与完整性提供形式地保证。请读者仅作参考。更多内容请加danei0707学习了解。欢迎关注“达内在线”参与分销，赚更多好礼。