论代码与注释

诗曰：

夭夭艳桃生于枝，虬虬桃枝旁向生。

使有桃芳而无枝，轻瓣何处得寻之。

即有桃枝无花冠，哪有闲人栽为观。

却令花枝得一处，清香散入九重佳。

此诗论桃芳与桃枝为相依者也，然代码与注释亦如此乎！

代码者，何也？砌之以函数语句，行之以编译运行。然开发者呕心沥血，未能完一项目之全体；既已完成，亦必有不足之阙漏。夫人之精力有限，则师传徒，徒复传徒，代代传之，方得精尽其项目。可后继之人，安知前人之旨意哉？

是必用注释矣。注释者，无与编运，无限句法，只求备述详尽，将大小细节，一一注明。注释大略置于所注之代码前，换行启之。常注释有二，一则为句注释，二则为块注释。句注如细细之批，详解语句之用意，或易错之处，亦可记已修正之误，以警后来者。块注释则不然，其常置于类、接口、函数等整体代码之前。述脉络之大体，点龙睛之算法。二则以相辅相成，毋令舍其一二。徒有句者，虽句句分明，然代码行进之方向，如障幕也，非利于续接；徒有块者，虽大意了然，然细节之处，多生奇异，使调试排查，仅之有错，不知错在何处，或往往修正为误，化简为繁，枉费经历也，其不知某句某意，不知该句之轻重，将酿大过矣。

呜呼，然现世之与码者，往全注与代码之优劣，而忘贻思路之足迹；码虽良，无注释，于外文之书籍何异？戏称为“屎山”，其知耻乎？悲矣斯人！