诠释注释——morning小品文

原创 2003年02月24日 09:07:00

【声明】如需复制、传播,请附上本声明,谢谢。原文出处:http://morningspace.51.net/,moyingzz@etang.com

  注释是源码的终生伴侣,这一点是毋庸置疑的。她通常用来解释源码的控制流程,或者是类、函数、变量的说明等等,用以体现程序书写者的意图、目的。关于注释的问题,归纳起来不外乎“何时写?”,“写什么?”,“怎么写?”。对于某些程序员而言,写注释似乎是一件很费脑筋的事情。试想,在酣畅淋漓的coding时,如何愿意打断思路去考虑注释的书写;而完成coding后,又如何愿意回过头去考虑添加注释呢?这种状况很容易养成习惯。本文准备就此提供一些一般性的建议,但并不涉及具体的注释格式和方法。这些内容可以在相关的书籍和文章中找到。

   注释首先应该不至于侮辱每个程序员的智力,一些显而易见的解释似乎是可以省略的,也不要简单重复源码已经表达的信息,因为这是多余的。不应该把添加注释看作是一种形式上的任务或责任,并且,这也不是简单的被动行为。

   注释应该易于阅读和理解,这不光是有利于自己,还包括他人,你的后继者可能会接手你的代码。正所谓利己利人,损人害己的事情是最可怕的。好的注释其实是需要文字功底的,它应该做到清晰、简洁、精准、有价值。

   注释的出现频率应该是适当的,她只在需要的地方才会出现,并且某处的内容也不易过分的多。过多的注释会把代码分割得支离破碎,以影响流畅性,从而影响阅读者思路的连贯性。大段的注释或许经常会被那些急性子的阅读者忽略掉,他到宁愿去啃那些硬梆梆的,却是实实在在的代码。

   代码随着时间的推移很有可能会慢慢改变其本来面目,一个粗心的、或是懒惰的程序员,极有可能忘记及时保持代码和注释的一致性。这样的错误或许优秀的程序员也可能会犯,人非圣贤,熟能无过。其实,保持这种一致性,本身就是编写代码以外的额外开销,它是必要的,却也需要付出成本。如果在开始写注释的时候就尽量考虑减少以后维护的代价,那么这种同步的维持会相对轻松些。可以在维护上少花些精力,此等好事,相信任何人都会赞成的,包括你和你的老板。一个显而易见的例子是:避免在注释里引用易变的代码信息,这是造成代码和注释不同步的一个重要诱因。

   切记,注释并没有强制约束力,这一点和文档相似。如果你没有遵守注释中所写明的某个函数的使用注意事项,程序仍可以顺畅地执行,直至遇到致命错误,或许你要为此付出痛苦调试的代价。所以,如果希望强制约束的话,就该尽可能利用程序设计语言自身的功能和特点,争取让编译器在生成可执行代码之前,自动帮你找到问题所在,或者是利用断言(assert)来澄清事实。

   规范化的注释还可以有助于自动生成部分开发文档,或许这可以免去你书写开发文档的一部分精力。Java Doc就是一个明显的例子。

   此外,注释还可以起一些额外的作用。比如,在写程序时,对于目前还未实现的代码,注释可以作为一种助记符或备忘录,以备经后在此处添加代码。它可以描述一个程序的局部流程,表达程序员的某些意图和思路。至于这些注释最终是否被保留,则视情形而定。用这种方式的一个好处是,尽管代码未曾实现,但是意识了然,并且这种行为没有破坏现有程序,它仍然可以被编译通过。另一个把注释作为助记的例子是,当你对某段代码的合理性表示怀疑而是时又想不到更有效的解决办法时,可以在旁边加上诸如“FIXME”这样的词并配以简短的说明。当你有足够精力来考虑这些曾被你怀疑为潜在问题的时候,一个简单的文字查找功能,就可以将这些危险的家伙全部揪出来(目前的文字编辑工具一般都会有Find甚至是Find In Files功能,应该善于运用这些强大的功能)。

   最后,对于那些过分热衷于注释的朋友,我想提醒一点:最后真正交付运行的唯有代码。如果代码完全可以说明一切,那么注释就是添足之笔;如果在考虑如何写注释时,代码本身却存在问题,请先关注一下你的代码和设计。

-morning-

问题 A: Good morning 【字符串的处理】

问题 A: Good morning 时间限制: 1 Sec 内存限制: 128 MB 提交: 57 解决: 22 题目描述 给定一个只有小写字母构成的非空字符串,可以从字...
  • qq_37383726
  • qq_37383726
  • 2017年03月05日 19:01
  • 276

如何运行C++ STL程序——morning小品文

如需复制、传播,请附上本声明,谢谢。原文出处:http://morningspace.51.net/,moyingzz@etang.com本文摘编自笔者自撰的《C++ STL轻松导学》,简单介绍了在特...
  • thesecondwoodstock
  • thesecondwoodstock
  • 2003年01月20日 09:45
  • 1180

奥运英语[12] 你今天早晨好吗 How are you this morning?

 http://www.eol.cn/olympic_study_5563/20070305/t20070305_221032.shtml 第12句  How are you this morning...
  • foreveryday007
  • foreveryday007
  • 2009年10月21日 11:04
  • 1183

洪峰的黑客道

洪峰的黑客道在这里。没有在中文媒介上看到相关报道,而是在Oreilly的Python DevCenter博客上看到的。如果是旧闻,只能说明俺自己人品不好。黑客道是洪峰成立的培训组织,用来培训功力扎实的...
  • g9yuayon
  • g9yuayon
  • 2007年05月09日 07:54
  • 10877

poj 1836 Alignment (最长上升子序列 N*log(n))@

In the army, a platoon is composed by n soldiers. During the morning inspection, the soldiers are al...
  • yjf3151731373
  • yjf3151731373
  • 2017年03月06日 15:27
  • 106

ocp-010

QUESTION NO: 10 You plan to collect the Automatic Workload Repository (AWR) data every Monday morni...
  • xuejiayue1105
  • xuejiayue1105
  • 2015年09月30日 20:33
  • 535

In the Morning

每天早上听到周华健的朋友对自己的感触很深,在这个学校待了三年了,没有做成一件自己认为成功的事,也许这就是学生时代吧,要不停的学习,不停的去补充自己,让自己变得好一点,能有个好的工作,也算给自己有个交待...
  • lichen396116416
  • lichen396116416
  • 2010年05月27日 06:58
  • 286

POJ 1836-Alignment(DP/LIS变形)

Alignment Time Limit: 1000MS   Memory Limit: 30000K Total Submissions: 13465   Acc...
  • qq_16255321
  • qq_16255321
  • 2014年11月16日 17:35
  • 632

二级指针和二维数组的比较

#include void func(char ** m) {        ++m;        cout } int main () {         static char...
  • SYP35
  • SYP35
  • 2015年09月15日 16:18
  • 246

in/on the morning

on the morning of July 21 I took a Greyhound bus from Los Angeles to Fresno On the morning of 28 Fe...
  • hxp42
  • hxp42
  • 2014年12月15日 10:16
  • 257
内容举报
返回顶部
收藏助手
不良信息举报
您举报文章:诠释注释——morning小品文
举报原因:
原因补充:

(最多只允许输入30个字)