JAVA技巧：注释规范整理分析

会计考友

一、布景
0 s- @; t8 f1 ~# `/ p; S! o　　1、当我们第一次接触某段代码，但又被要求在极短的时刻内有用地剖析这段代码，我们需要什么样的注释信息？
　　2、怎么样避免我们的注释冗长而且凌乱不胜呢？
　　3、在多人协同开发、维护的今天，我们需要怎么样的注释来保证高质、高交的进行开发和维护工作呢？
　　二、意义
　　轨范中的注释是轨范设计者与轨范阅读者之间通信的主要手段。应用注释规范对于软件自己和软件开发人员而言尤为主要。而且在风行的火速开发思惟中已经提出了将注释转为代码的概念。好的注释规范可以尽可能的削减一个软件的维护成本 , 而且几乎没有任何一个软件，在颇整个生命周期中，均由最初的开发人员来维护。好的注释规范可以改善软件的可读性，可以闪开发人员尽快而彻底地舆解新的代码。好的注释规范可以最大限度的提高团队开发的合作效率。持久的规范性编码还可以闪开发人员养成精采的编码习惯，甚至磨炼出加倍严谨的思维能力。
　　三、注释的原则
　　1、 注释形式统一
* |5 Z+ W+ I, V: ?　　在整个应用轨范中，利器具有一致的标点和结构的样式来机关注释。如不美观在其他项目组发现他们的注释规范与这份文档分歧，按照他们的规范写代码，不要试图在既成的规范系统中惹人新的规范。
　　2、 注释的精练
　　内容要简单、了然、寄义切确，防止注释的多义性，错误的注释不单无益反而有害。
; t9 Y- f+ L) o+ M2 R: A+ g　　3、 注释的一致性
　　在写代码之前或者边写代码边写注释，因为往后很可能没有时刻来这样做。此外，如不美观有机缘复查已编写的代码，在今天看来很较着的工具六周往后或许就不较着了。凡是描述性注释先于代码建树，诠释性注释在开发过程中建树，提醒性注释在代码完成之后建树。改削代码的同时改削响应的注释，以保证代码与注释的同步。
0 B# ~9 K: b0 A! M! j0 U　　4、 注释的位置
1 U) A" Y$ A! }& X% B) @　　保证注释与其描述的代码相邻，即注释的就近原则。对代码的注释应放在其上方相邻或右方的位置，不成放不才方。避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不外在批注变量声明时，行尾注释是合适的；在这种情形下，将所有行尾注释要对齐。
　　5、 注释的数目
3 e1 q3 U( [5 q7 l& q+ t; s　　注释必不成少，但也不应过多，在现实的代码规范中，要求注释占轨范代码的比例达到20%摆布。注释是对代码的“提醒”，而不是文档，轨范中的注释不成鹊巢鸠占，注释太多了会让人目炫缭乱，注释的花腔要少。不要被动的为写注释而写注释。
+ ^0 g2 F) }$ N  i　　6、删除无用注释
　　在代码交付或部署发布之前，必需删失踪姑且的或无关的注释，以避免在日后的维护工作中发生杂乱。
, g/ j6 Q  v5 Q/ o8 j- p0 b　　7、 复杂的注释
5 P! P0 @% S* d, o/ J6 Z  d　　如不美观需要用注释来诠释复杂的代码，请搜检此代码以确定是否应该重写它。尽一切可能不注释难以理解的代码，而应该重写它。尽管一般不应该为了使代码更简单便于使用而牺牲机能，但必需连结机能和可维护性之间的平衡。
　　8、 多余的注释
　　描述轨范功能和轨范各组成部门彼此关系的高级注释是最有用的，而逐行诠释轨范若何工作的初级注释则晦气于读、写和改削，是不需要的，也是难以维护的。避免每行代码都使用注释。如不美观代码原本就是清嚣张、一目了然的则不加注释，避免多余的或不恰当的注释呈现。
; [4 n/ c' i) F, Z  [" ]) D8 X2 x* ~　　9、必加的注释
　　典型算法必需有注释。在代码不了了或不成移植处必需有注释。在代码改削处加上改削标识的注释。在轮回和逻辑分支组成的代码中添加注释。为了防止问题一再呈现，对错误修复息争决体例的代码使用注释，尤其是在团队情形中。
　　10、注释在编译代码时会被忽略，不编译到最后的可执行文件中，所以注释不
　　会增添可执行文件的巨细。