软件开发编码规范笔记--注释规范

    最近软件工程课程强调了一些编码规范，觉得很有必要记录下来；从而在以后的编码过程中养成良好的编码习惯。

---

注释规范

        注释是用自然语言对代码的解释和说明，其目的是提高代码的可读性，不会被计算机编译。很多人有一个误区，那就是注释越多越好，其实不然。注释产生的原因,本质是代码的可读性太差，我们应该遵守良好的编程规范和命名风格，努力提高代码的可读性，从而减少注释。

        以下是注释可能会出现的几个问题：注释可能会将代码块分割，降低程序的可读性；注释不一定真实的反应了代码的意图，可能具有误导性；注释需要随着代码的更新而不断地更新，增加了维护成本。一旦注释过时，可能产生严重的后果。 接下来介绍一些添加注释的建议。

---

       建议1：不要做代码的重复。（不过有时候写不出代码的时候，敲敲看起来没什么用的注释也能骗自己在干活 ^-^）

// Class representing a point.
class Point {
    private double X;
    private double Y;
    //Get the X value.
    public double getX(){
        return X;
    }
    //Get the Y value.
    public double getY(){
        return Y;
    }
}

---

         建议2：避免形式主义的注释。

 //This is a cute Dog
private String Dog;

---

        建议3： 尽量不要做代码的解释。(这个建议辩证看待吧)

        建议4：对代码的意图进行阐释。描述代码是用来做什么的而不是代码怎么做的，这是最有用的注释类型。(感觉还是要对自己写了的代码多思考，明白自己想让这段代码干什么、在什么地方可能被用到、在什么地方可以复用、什么地方冗余..才能慢慢写出意图明确的注释)

        建议5：确保注释如实反映代码的本意。如果某个函数的注释与函数的代码本意不符，那将会对函数调用者产生误导。注释必须随着代码的更新而不断地更新，注释版本落后于代码版本也会歪曲代码的本意。

        建议6：可以添加一些提供信息的注释。如在代码开头添加版权和著作权的声明、描述某个抽象方法的返回值。

---

        其实，如果不是大工程大项目，或者学科专业性极强的代码。我认为没有注释是最好的注释..