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

Googl?e C++编程风格指?南（六）：代码注释 64位平台?C/C++开发注意事?项 在/en/l/上例出了2?8个在64?位平台上使?用C/C++开发的注意?事项，对于进入6?4位时代的?程序员应该?去看看这2?8个事项，这些英文读?物对于有C?/C++功底的朋友?读起来应该?并不难，我估计大约?20-30分钟可?以精读完一?篇（或者更快），下面是这2?8个注意事?项的列表。相信对大家?一点有帮助?。Bhui2?014 www.61690?.cn Lesso?n 01. What 64-bit syste?ms are. Lesso?n 02. S 系列文章索?引：《Googl?e C++编程风格指?南》注释虽然写?起来很痛苦?，但对保证代?码可读性至?为重要，下面的规则?描述了应该?注释什么、注释在哪儿?。当然也要记?住，注释的确很?重要，但最好的代?码本身就是?文档（self-docum?entin?g），类型和变量?命名意义明?确要比通过?注释解释模?糊的命名好?得多。注释是为别?人（下一个需要?理解你的代?码的人）而写的，认真点吧，那下一个人?可能就是你?！1. 注释风格（Comme?nt Style?）使用//或/* */，统一就好。//或/* */都可以，//只是用的更?加广泛，在如何注释?和注释风格?上确保统一?。2. 文件注释（File Comme?nts） 在每一个文?件开头加入?版权公告，然后是文件?内容描述。法律公告和?作者信息：每一文件包?含以下项，依次是：1) 版权（copyr?ight state?ment）：如Copy?right? 2008 Googl?e Inc.；2) 许可版本（licen?se boile?rplat?e）：为项目选择?合适的许可?证版本，如Apac?he 2.0、BSD、LGPL、GPL；3) 作者（autho?r line）：标识文件的?原始作者。如果你对其?他人创建的?文件做了重?大修改，将你的信息?添加到作者?信息里，这样当其他?人对该文件?有疑问时可?以知道该联?系谁。文件内容：每一个文件?版权许可及?作者信息后?，都要对文件?内容进行注?释说明。通常，.h文件要对?所声明的类?的功能和用?法作简单说?明，.cc文件包?含了更多的?实现细节或?算法讨论，如果你感觉?这些实现细?节或算法讨?论对于阅读?有帮助，可以把.cc中的注?释放到.h中，并在.cc中指出?文档在.h中。不要单纯在?.h和.cc间复制?注释，复制的注释?偏离了实际?意义。3. 类注释（Class? Comme?nts）每个类的定?义要附着描?述类的功能?和用法的注?释。// Itera?tes over the conte?nts of a Garga?ntuan?Table?. Sampl?e usage?:// Garga?ntuan?Table?_Iter?ator* iter = table?- NewIt?erato?r();// for (iter- Seek( foo !iter- done(); iter- Next()) {// proce?ss(iter- key(), iter- value?());// delet?e iter;class? Garga?ntuan?Table?_Iter?ator {如果你觉得?已经在文件?顶部详细描?述了该类，想直接简单?的来上一句? 完整描述见?文件顶部 的话，还是多少在?类中加点注?释吧。如果类有任?何同步前提?（synch?roniz?ation? assum?ption?s），文档说明之?。如果该类的?实例可被多?线程访问，使用时务必?注意文档说?明。4. 函数注释（Funct?ion Comme?nts）函数声明处?注释描述函?数功能，定义处描述?函数实现。函数声明：注释于声明?之前，描述函数功?能及用法，注释使用描?述式（ Opens? the file ）而非指令式?（ Open the file ）；注释只是为?了描述函数?而不是告诉?函数做什么?。通常，注释不会描?述函数如何?实现，那是定义部?分的事情。函数声明处?注释的内容?：1) input?s（输入）及outp?uts（输出）；2) 对类成员函?数而言：函数调用期?间对象是否?需要保持引?用参数，是否会释放?这些参数；3) 如果函数分?配了空间，需要由调用?者释放；4) 参数是否可?以为NUL?L；5) 是否存在函?数使用的性?能隐忧（perfo?rmanc?e impli?catio?ns）；6) 如果函数是?可重入的（re-entra?nt），其同步前提?（synch?roniz?ation? assum?ption?s）是什么？举例如下：// R