Google C++编程风格指南(六)：代码注释.doc

GoogleC++编程风格指南（六）：代码注释
64位平台C/C++开发注意事项
在/en/l/上例出了28个在64位平台上使用C/C++开发的注意事项，对于进入64位时代的程序员应该去看看这28个事项，这些英文读物对于有C/C++功底的朋友读起来应该并不难，我估计大约20-30分钟可以精读完一篇（或者更快），下面是这28个注意事项的列表。相信对大家一点有帮助。Bhui2014HYPERLINK"http://www.61690.cn"www.61690.cnLesson01.What64-bitsystemsare.Lesson02.S
系列文章索引：《GoogleC++编程风格指南》注释虽然写起来很痛苦，但对保证代码可读性至为重要，下面的规则描述了应该注释什么、注释在哪儿。当然也要记住，注释的确很重要，但最好的代码本身就是文档（self-documenting），类型和变量命名意义明确要比通过注释解释模糊的命名好得多。注释是为别人（下一个需要理解你的代码的人）而写的，认真点吧，那下一个人可能就是你！1.注释风格（CommentStyle）使用//或/**/，统一就好。//或/**/都可以，//只是用的更加广泛，在如何注释和注释风格上确保统一。2.文件注释（FileComments）在每一个文件开头加入版权公告，然后是文件内容描述。法律公告和作者信息：每一文件包含以下项，依次是：1)版权（copyrightstatement）：如Copyright2008GoogleInc.；2)许可版本（licenseboilerplate）：为项目选择合适的许可证版本，如Apache2.0、BSD、LGPL、GPL；3)作者（authorline）：标识文件的原始作者。如果你对其他人创建的文件做了重大修改，将你的信息添加到作者信息里，这样当其他人对该文件有疑问时可以知道该联系谁。文件内容：每一个文件版权许可及作者信息后，都要对文件内容进行注释说明。通常，.h文件要对所声明的类的功能和用法作简单说明，.cc文件包含了更多的实现细节或算法讨论，如果你感觉这些实现细节或算法讨论对于阅读有帮助，可以把.cc中的注释放到.h中，并在.cc中指出文档在.h中。不要单纯在.h和.cc间复制注释，复制的注释偏离了实际意义。3.类注释（ClassComments）每个类的定义要附着描述类的功能和用法的注释。//IteratesoverthecontentsofaGargantuanTable.Sampleusage://GargantuanTable_Iterator*iter=table-NewIterator();//for(iter-Seek(foo!iter-done();iter-Next()){//process(iter-key(),iter-value());//deleteiter;classGargantuanTable_Iterator{如果你觉得已经在文件顶部详细描述了该类，想直接简单的来上一句完整描述见文件顶部的话，还是多少在类中加点注释吧。如果类有任何同步前提（synchronizationassumptions），文档说明之。如果该类的实例可被多线程访问，使用时务必注意文档说明。4.函数注释（FunctionComments）函数声明处注释描述函数功能，定义处描述函数实现。函数声明：注释于声明之前，描述函数功能及用法，注释使用描述式（Opensthefile）而非指令式（Openthefile）；注释只是为了描述函数而不是告诉函数做什么。通常，注释不会描述函数如何实现，那是定义部分的事情。函数声明处注释的内容：1)inputs（输入）及outputs（输出）；2)对类成员函数而言：函数调用期间对象是否需要保持引用参数，是否会释放这些参数；3)如果函数分配了空间，需要由调用者释放；4)参数是否可以为NULL；5)是否存在函数使用的性能隐忧（performanceimplications）；6)如果函数是可重入的（re-entrant），其同步前提（synchronizationassumptions）是什么？举例如下：//Returnsaniteratorforthistable.Itistheclient”s//responsibilitytodeletetheiteratorwhenitisdonewithit,//anditmustnotusetheiteratoroncetheGargantuanTableobject//onwhichtheiteratorwascreatedhasbeendeleted.//Theiteratorisinitiallypositionedatthebeginningofthet