16. 小议注释

小议注释

        我大学时的第一堂编程课，老师发了两张BASIC编程纸，上面的作业是“编写一个程序，输入10个保龄球分数并计算平均值”。接着老师离开了。这有多难？我已记不得我最终的答案，但是我确定使用了一个FOR/NEXT循环，并且总共不超过15行。编程纸，你们可能没有听说过，但我们过去常常在上面手写代码，然后才输入到计算机中，每张可以容纳约70行代码。我很疑惑，为什么老师会给我们两张编程纸。由于我的字迹很潦草，我在第二张纸上很细致地将代码重抄了一遍，希望能因为漂亮的字迹得到点加分。
        让我始料不及的是，下次课开始时我收回作业，只得到了一个勉强及格的分数。（这对我接下来的整个大学生涯都是一个预示。）我精致的手写代码顶部几个潦草的字：“没有注释？”
        老师和我都知道这段程序是做什么的，但这是不足的。作业的一部分收获是教育了我，我的代码应该向我后面的程序员解释它自己。这堂课让我永世难忘。
        注释并不邪恶。对于编程它们是必需的，就像基本分支和循环结构。大多数的现代语言都有类似于javadoc那样的工具，能处理正确格式的注释，自动以之生成一个API文档。这是一个很好的开始，但并不足够。你的代码里面应该有代码是用来做什么的说明。编程，像一句格言说的，“难写的就会很难读”，会给你的客户、雇员、同事以及未来的自己造成伤害。
        另一方面，我们也不能把注释做过头了。确保你的注释会让代码更清晰，而不是更费解。在代码里面适量加上相关的、解释代码任务的注释。你的头注释应该给任何程序员足够的信息去使用你的代码，而无需阅读它，同时内联的注释帮助下一个开发者修正它或者扩展它。
        曾经在一个工作中，我不同意上面的人做的一个设计决定。在感觉到相当尖刻，就像年轻的程序员经常做的，我将提示我使用他们的设计的邮件中的文字粘贴到头件的头注释里面。结果是，这里的经理确实在我提交后之后审核了代码。这是我首次接触到”职业绊脚石“这个词。

原文：A Comment on Comments byCal Evans