thing_16

A Comment on Comments
https://97-things-every-x-should-know.gitbooks.io/97-things-every-programmer-should-know/content/en/thing_16/

In my first programming class in college, my teacher handed out two BASIC coding sheets. On the board, the assignment read “Write a program to input and average 10 bowling scores.” Then the teacher left the room. How hard could this be? I don’t remember my final solution but I’m sure it had a FOR/NEXT loop in it and couldn’t have been more than 15 lines long in total. Coding sheets — for you kids reading this, yes, we used to write code out longhand before actually entering it into a computer — allowed for around 70 lines of code each. I was very confused as to why the teacher would have given us two sheets. Since my handwriting has always been atrocious, I used the second one to recopy my code very neatly, hoping to get a couple extra points for style.

Much to my surprise, when I received the assignment back at the start of the next class, I received a barely passing grade. (It was to be an omen to me for the rest of my time in college.) Scrawled across the top of my neatly copied code, “No comments?”

It was not enough that the teacher and I both knew what the program was supposed to do. Part of the point of the assignment was to teach me that my code should explain itself to the next programmer coming behind me. It’s a lesson I’ve not forgotten.

Comments are not evil. They are as necessary to programming as basic branching or looping constructs. Most modern languages have a tool akin to javadoc that will parse properly formatted comments to automatically build an API document. This is a very good start, but not nearly enough. Inside your code should be explanations about what the code is supposed to be doing. Coding by the old adage, “If it was hard to write, it should be hard to read,” does a disservice to your client, your employer, your colleagues, and your future self.

On the other hand, you can go too far in your commenting. Make sure that your comments clarify your code but do not obscure it. Sprinkle your code with relevant comments explaining what the code is supposed to accomplish. Your header comments should give any programmer enough information to use your code without having to read it, while your in-line comments should assist the next developer in fixing or extending it.

At one job, I disagreed with a design decision made by those above me. Feeling rather snarky, as young programmers often do, I pasted the text of the email instructing me to use their design into the header comment block of the file. It turns out that managers at this particular shop actually reviewed the code when it was committed. It was my first introduction to the term career-limiting move.

by Cal Evans

在我大学的第一节编程课上，老师分发了两张BASIC编码表。在黑板上，作业上写着“写一个程序输入并平均10个保龄球分数。”然后老师离开了房间。这有多难？我不记得我的最终解决方案了，但我确信它有一个FOR/NEXT循环，总共不可能超过15行。编码表——对你们这些读到这篇文章的孩子来说，是的，我们过去常常在把代码输入计算机之前用手写出来——每个允许大约70行代码。我很困惑，为什么老师会给我们两张纸。由于我的笔迹一直很糟糕，我用第二个非常工整地重新编写了代码，希望能在风格上多加几分。
令我惊讶的是，当我在下一节课开始时收到作业时，我的成绩勉强及格。（这对我大学剩下的时间来说是一个预兆。）在我工整复制的代码顶部，“没有评论？”
我和老师都知道这个程序应该做什么还不够。作业的部分目的是教我，我的代码应该向后面的下一个程序员解释。这是我没有忘记的一课。
评论并不邪恶。它们对于编程来说就像基本的分支或循环结构一样必要。大多数现代语言都有一个类似于javadoc的工具，可以解析格式正确的注释，从而自动构建API文档。这是一个非常好的开始，但还远远不够。在代码内部应该有关于代码应该做什么的解释。用一句古老的格言“如果它很难写，就应该很难读”来编码，这对你的客户、雇主、同事和未来的自己都是有害的。
另一方面，你的评论可能会过分。确保你的注释澄清了你的代码，但不要混淆它。在你的代码中撒上相关的注释，解释代码应该完成什么。你的头注释应该给任何程序员足够的信息来使用你的代码，而不必阅读它，而你的内联注释应该帮助下一个开发人员修复或扩展它。
在一份工作中，我不同意我上面的人做出的设计决定。就像年轻程序员经常做的那样，我感觉很刻薄，于是把指示我使用他们设计的电子邮件文本粘贴到了文件的标题评论块中。事实证明，这家特定商店的经理实际上在提交代码时对其进行了审查。这是我第一次介绍职业生涯限制搬家这个术语。
作者：Cal Evans