诗曰:
夭夭艳桃生于枝,虬虬桃枝旁向生。
使有桃芳而无枝,轻瓣何处得寻之。
即有桃枝无花冠,哪有闲人栽为观。
却令花枝得一处,清香散入九重佳。
此诗论桃芳与桃枝为相依者也,然代码与注释亦如此乎!
代码者,何也?砌之以函数语句,行之以编译运行。然开发者呕心沥血,未能完一项目之全体;既已完成,亦必有不足之阙漏。夫人之精力有限,则师传徒,徒复传徒,代代传之,方得精尽其项目。可后继之人,安知前人之旨意哉?
是必用注释矣。注释者,无与编运,无限句法,只求备述详尽,将大小细节,一一注明。注释大略置于所注之代码前,换行启之。常注释有二,一则为句注释,二则为块注释。句注如细细之批,详解语句之用意,或易错之处,亦可记已修正之误,以警后来者。块注释则不然,其常置于类、接口、函数等整体代码之前。述脉络之大体,点龙睛之算法。二则以相辅相成,毋令舍其一二。徒有句者,虽句句分明,然代码行进之方向,如障幕也,非利于续接;徒有块者,虽大意了然,然细节之处,多生奇异,使调试排查,仅之有错,不知错在何处,或往往修正为误,化简为繁,枉费经历也,其不知某句某意,不知该句之轻重,将酿大过矣。
呜呼,然现世之与码者,往全注与代码之优劣,而忘贻思路之足迹;码虽良,无注释,于外文之书籍何异?戏称为“屎山”,其知耻乎?悲矣斯人!