注释的注释

原文链接

在我大学的第一堂编程课上,老师发了两张BASIC代码卡片。在黑板上写下:“写一段程序用于输入并计算10个保龄球的平均成绩。”然后老师离开了教室。这道题有多难呢?我不记得最后是如何解决的,但我很清楚用到了FOR/NEXT循环,并且总过不超过15行代码。代码卡片,对于少年时期的你而言,是的,我们那时在把它敲进计算机前确实是手写代码,大概允许每人写70行。我很懵逼,为什么老师要给我们两张卡片。由于我的书法很搓,我就非常工整地把代码抄到另一张,希望在风格上得到加分项。

当时我就震惊了!下堂课我拿到成绩一看,差点不及格。(这也成了我大学剩下时光里的征兆。)在我工整的代码头上写道——“注释被你吃了?”

我和老师都知道一段程序是如何运行的还不够。这次作业的另一点教育了我,我的代码应该要解释给下一个到来的程序员。这真是难忘的一颗啊!

注释不是坏事。它们在程序的分支或循环控制语句中尤为重要。很多现代语言都有类似javadoc的工具,可以根据正确格式的注释语法自动构建API文档。这是非常好的开始,但还不够。你在代码内部还要说明代码会做些什么。编程格言:如何不好写,肯定不好读。这会伤害你的客户、你的员工、你的同事、以及未来的你。

另一方面,你可以在注释的路上走的很远。注释要做到很清楚而不是懵懂。利用注释来说明你的代码将完成什么。头部注释应该给予程序员足够的信息,让他不用读代码内容就可以调用它,行内注释应该帮助其他开发者修复或扩展你的代码。

在一次工作中,我不同意一个由我上级作出的设计决定。正如年轻人经常这么干,感觉很鸡贼,我把电子邮件里指导我使用他们设计好的模版,直接粘贴到文件的头部注释当中。而实际情况是,当代码提交后,经理会躲在某个咖啡店里把代码审查了。这是我第一次提到职业瓶颈。(It was my first introduction to the term career-limiting move最后这句不会翻译🙂)

0%