关于注释

Posted 2020-08-15 撿忔

一，为什么要注释

1.帮助我们理解思路，如果有清晰的文档注释我们可以快速理清思路，而不用耗费太多的时间在回想思考和debug上面

2.注释可以让我们快速方便的知道，被注释事物的内涵和意义，不管在编程还是维护中都可以帮我们节省大量的寻找和思考时间，我们可以根据注释快速定位

3.增强代码的可阅读性

二.五种应该避免的代码注释

通常，我们阅读软件比编写软件花费的时间要更多。虽然我从未见过任何科学研究能够证明这一点，但是在软件领域，它就好比一个教条或者信念如此的根深蒂固。正因为编写软件要比阅读软件要容易，因此代码的可读性而显得尤为重要。程序员可以通过一些技术来实现它，其中一点就包括代码注释。

关于代码注释的文章，网络上有很多讨论。我们应该使用注释来解释代码吗？还是应该注重编写表达式代码而无需阅读注释？Joe Kunk曾发表过一篇文章《To Comment or Not to Comment》其中有段内容是说所谓的好代码是指我们应该避免注释，因为注释通常是用来解释/隐藏恶意代码。

下面就来讨论下避免写代码注释的五大理由：

1. 程序员更加倾向于鼓励”坏“代码。

有一种说法，有代码注释的就是好代码，因此，程序员经常在代码边上写注释，使其看起来更加出色。如果我们把代码注释当做一种信号，那么也许我们正在编写坏代码。每当我们写注释时应该思考如何使代码看清来更加洁净。

2. 花费更多时间来编写和维护

如果注释没有跟随代码的变化而变化，即使是正确的注释也没有用。注释通常作为代码的第二个版本。当为某个函数写注释时我们需要不断的重复自己，这就违反了DRY(Don’t Repeat Yourself) 原则。花费时间来增加复杂性，软件需求改变了，代码也随之跟着变化。如果我们写注释，这就意味着必须去维护注释。因此，除非是很必须要，否则我们应该拒绝在注释上花费双倍时间，相反我们可以利用这些时间来提高代码的质量或开发新的特性。

3. 注释不是测试/验证

修改代码可以依赖工具，比如使用编译器、IDEs及单元测试；而注释却不能。注释没有这些工具，你无法依赖工具或者单元测试在正确的地方或者过期后来确保它们的正确性。一旦你写了注释，没有测试模块来验证它的正确性，一旦这个注释失败了，那么它就永远的失败了。

4. 注释没有代码文档可靠

通常，注释过期后，它们往往与代码失去了连接性。程序员阅读这些注释或许被“欺骗”了。即使不断的更新了代码注释，唯一了解的是这个代码应该是什么以及它的可读性。举个例子，如果老本问我们如果项目发生了更改，我们从哪能看出？是代码还是注释？——答案当然是代码。

5. 代码注释风格填补了屏幕空间

采用标准化的注释尤为重要，某些注释标准（如同下面）使用了很多行，这就要求你尽可能多的阅读更多代码。

 

[js] view plaincopy

 

1. /** 
2. *  
3. * @param title The title of the CD 
4. * @param author The author of the CD 
5. * @param tracks The number of tracks on the CD 
6. * @param durationInMinutes The duration of the CD in minutes 
7. */  
8. public void addCD(String title, String author,   
9. int tracks, int durationInMinutes) {  
10. CD cd = new CD();  
11. cd.title = title;  
12. cd.author = author;  
13. cd.tracks = tracks;  
14. cd.duration = duration;  
15. cdList.add(cd);  
16. } 

17. 下面是stackoverflow网站上网友针对你看到过的最好的代码注释是什么样的？这个问题给出的回答的前10条：

    1.

    // 亲爱的维护者： // 如果你尝试了对这段程序进行‘优化’， // 并认识到这种企图是大错特错，请增加 // 下面这个计数器的个数，用来对后来人进行警告： // 浪费在这里的总时间 = 39h

     

    2.

    /** * 致终于来到这里的勇敢的人： 你是被上帝选中的人，英勇的、不辞劳苦的、不眠不修的来修改 我们这最棘手的代码的编程骑士。你，我们的救世主，人中之龙， 我要对你说：永远不要放弃，永远不要对自己失望，永远不要逃走，辜负了自己。 永远不要哭啼，永远不要说再见。永远不要说谎来伤害自己。 */

     

    3.

    Exception up = new Exception("Something is really wrong."); throw up;

    4.

    // 一些修改1 - 2002/6/7 增加临时的跟踪登录界面 // 一些修改2 - 2007/5/22 我临时的犯傻

     

    5.

    #define TRUE FALSE //逗一逗调试程序的傻瓜们

    6.

    if (/*you*/ $_GET[‘action‘]) { //celebrate(恭喜)

     

    7.

    // 如果这段代码好用，那它是Paul DiLascia写的。 //如果不好用，我不知道是谁写的。

    8.

    //写这段代码的时候，只有上帝和我知道它是干嘛的 //现在，只有上帝知道

     

    9.

    // 晕了，以后再修改

    10.

    // 神奇。勿动。

 

PS：本文所说的“避免代码注释"，并不是说就不写代码注释，而是尽量避免去写代码注释，假如你认为值得也可以这么做

四：代码注释快捷键