代码注释规范整理VIP专享

JAVA 注释规范 一、背景 1 、当我们第一次接触某段代码，但又被要求在极短的时间内有效地分析这段代码，我们需要什么样的注释信息？ 2 、怎么样避免我们的注释冗长而且凌乱不堪呢？ 3 、在多人协同开发、维护的今天，我们需要怎么样的注释来保证高质、高交的进行开发和维护工作呢？ 二、意义 程序中的注释是程序设计者与程序阅读者之间通信的重要手段。应用注释规范对于软件本身和软件开发人员而言尤为重要。并且在流行的敏捷开发思想中已经提出了将注释转为代码的概念。好的注释规范可以尽可能的减少一个软件的维护成本 , 并且几乎没有任何一个软件，在其整个生命周期中，均由最初的开发人员来维护。好的注释规范可以改善软件的可读性，可以让开发人员尽快而彻底地理解新的代码。好的注释规范可以最大限度的提高团 队 开发的合 作效率 。长期的规范性编 码还 可以让开发人员养 成良 好的编 码习 惯 ，甚 至 锻 炼 出更 加 严 谨的思维能力 。 三 、注释的原 则 1、 注释形 式 统 一 在整个应用程序中，使 用具 有一致 的标 点 和结 构 的样式 来构 造 注释。如 果 在其他 项 目 组 发现他 们的注释规范与这份 文 档 不同，按 照 他 们的规范写 代码，不要试 图 在既 成的规范系 统 中引入 新的规范。 2、 注释的简 洁 内容 要简 单 、明 了、含 义准 确 ，防 止 注释的多义性，错 误 的注释不但无 益 反 而有害 。 3 、 注释的一致 性 在写 代码之前 或 者边 写 代码边 写 注释，因 为以后 很 可能没有时间来这样做 。另 外 ，如 果 有机会 复 查 已编 写 的代码，在今天看 来很 明 显 的东 西 六 周以后 或 许 就 不明 显 了。通常 描 述 性注释先 于代码创 建 ，解释性注释在开发过 程中创 建 ，提示 性注释在代码完 成之后 创 建 。修 改代码的同时修改相应的注释，以保证代码与注释的同步。 4、 注释的位置 保证注释与其描述的代码相邻，即注释的就近原则。对代码的注释应放在其上方相邻或右方的位置，不可放在下方。避免在代码行的末尾添加注释；行尾注释使代码更难阅读。不过在批注变量声明时，行尾注释是合适的；在这种情况下，将所有行尾注释要对齐。 5、 注释的数量 注释必不可少，但也不应过多，在实际的代码规范中，要求注释占程序代码的比例达到20%左右。注释是对代码的“提...