Google C++ 编程风格指南：注释

迈不过友情╰ 2023-03-13 06:11 22阅读 0赞

<table> 
 <tbody> 
  <tr> 
   <td style="vertical-align:top;"> 
    <div style="margin-left:0px;"> 
     <div style="margin-left:0px;"> 
      <div style="margin-left:0px;"> 
       <table> 
        <tbody> 
         <tr> 
          <td> 
           <div style="margin-left:0px;"> 
            <strong>注释虽然写起来很痛苦, 但对保证代码可读性至关重要. 下面的规则描述了如何注释以及在哪儿注释. 当然也要记住: 注释固然很重要, 但最好的代码本身应该是自文档化. 有意义的类型名和变量名, 要远胜过要用注释解释的含糊不清的名字.</strong> 
           </div> 
           <div style="margin-left:0px;"> 
            <strong>你写的注释是给代码读者看的: 下一个需要理解你的代码的人. 慷慨些吧, 下一个人可能就是你!</strong> 
           </div> <strong>7.1. 注释风格</strong> 
           <div style="margin-left:0px;"> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">使用 // 或 /* */, 统一就好.</span></strong> 
            </div> &nbsp; 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">// 或 /* */ 都可以; 但 // 更 常用. 要在如何注释及注释风格上确保统一.</span></strong> 
            </div> 
           </div> <br><strong>7.2. 文件注释</strong> 
           <div style="margin-left:0px;"> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">在每一个文件开头加入版权公告, 然后是文件内容描述.</span></strong> 
            </div> &nbsp; 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">法律公告和作者信息:</span></strong> 
            </div> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">每个文件都应该包含以下项, 依次是:</span></strong> 
            </div> &nbsp; 
            <ul style="margin-left:14px;"> 
             <li><strong><span style="color:#444444;">版权声明 (比如, Copyright 2008 Google Inc.)</span></strong></li> 
             <li><strong><span style="color:#444444;">许可证. 为项目选择合适的许可证版本 (比如, Apache 2.0, BSD, LGPL, GPL)</span></strong></li> 
             <li><strong><span style="color:#444444;">作者: 标识文件的原始作者.</span></strong></li> 
            </ul> &nbsp; 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">如果你对原始作者的文件做了重大修改, 将你的信息添加到作者信息里. 这样当其他人对该文件有疑问时可以知道该联系谁.</span></strong> 
            </div> &nbsp; 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">文件内容:</span></strong> 
            </div> 
            <blockquote> 
             <div style="margin-left:0px;"> 
              <strong><span style="color:#444444;">紧接着版权许可和作者信息之后, 每个文件都要用注释描述文件内容.</span></strong> 
             </div> 
             <div style="margin-left:0px;"> 
              <strong><span style="color:#444444;">通常, .h 文件要对所声明的类的功能和用法作简单说明. .cc 文件通常包含了更多的实现细节或算法技巧讨论, 如果你感觉这些实现细节或算法技巧讨论对于理解 .h 文件有帮助, 可以将该注释挪到 .h, 并在 .cc 中指出文档在 .h.</span></strong> 
             </div> 
             <div style="margin-left:0px;"> 
              <strong><span style="color:#444444;">不要简单的在 .h 和 .cc 间复制注释. 这种偏离了注释的实际意义.</span></strong> 
             </div> 
            </blockquote> 
           </div> <br><strong>7.3. 类注释</strong> 
           <div style="margin-left:0px;"> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">每个类的定义都要附带一份注释, 描述类的功能和用法.</span></strong> 
            </div> 
            <br> 
            <strong><span style="color:#444444;"><span style="color:#999988;">// Iterates over the contents of a GargantuanTable.&nbsp;&nbsp;Sample usage:</span><span style="color:#999988;">//&nbsp; &nbsp; GargantuanTable_Iterator* iter = table-&gt;NewIterator();</span><span style="color:#999988;">//&nbsp; &nbsp; for (iter-&gt;Seek("foo"); !iter-&gt;done(); iter-&gt;Next()) { </span><span style="color:#999988;">//&nbsp; &nbsp;&nbsp; &nbsp;process(iter-&gt;key(), iter-&gt;value());</span><span style="color:#999988;">//&nbsp; &nbsp; }</span><span style="color:#999988;">//&nbsp; &nbsp; delete iter;</span>class GargantuanTable_Iterator {&nbsp; &nbsp; ...};</span></strong> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">如果你觉得已经在文件顶部详细描述了该类, 想直接简单的来上一句 “完整描述见文件顶部” 也不打紧, 但务必确保有这类注释.</span></strong> 
            </div> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">如果类有任何同步前提, 文档说明之. 如果该类的实例可被多线程访问, 要特别注意文档说明多线程环境下相关的规则和常量使用.</span></strong> 
            </div> 
           </div> <br><strong>7.4. 函数注释</strong> 
           <div style="margin-left:0px;"> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">函数声明处注释描述函数功能; 定义处描述函数实现.</span></strong> 
            </div> &nbsp; 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">函数声明:</span></strong> 
            </div> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">注释位于声明之前, 对函数功能及用法进行描述. 注释使用叙述式 (“Opens the file”) 而非指令式 (“Open the file”); 注释只是为了描述函数, 而不是命令函数做什么. 通常, 注释不会描述函数如何工作. 那是函数定义部分的事情.</span></strong> 
            </div> &nbsp; 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">函数声明处注释的内容:</span></strong> 
            </div> &nbsp; 
            <ul style="margin-left:14px;"> 
             <li><strong><span style="color:#444444;">函数的输入输出.</span></strong></li> 
             <li><strong><span style="color:#444444;">对类成员函数而言: 函数调用期间对象是否需要保持引用参数, 是否会释放这些参数.</span></strong></li> 
             <li><strong><span style="color:#444444;">如果函数分配了空间, 需要由调用者释放.</span></strong></li> 
             <li><strong><span style="color:#444444;">参数是否可以为 NULL.</span></strong></li> 
             <li><strong><span style="color:#444444;">是否存在函数使用上的性能隐患.</span></strong></li> 
             <li><strong><span style="color:#444444;">如果函数是可重入的, 其同步前提是什么?</span></strong></li> 
            </ul> &nbsp; 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">举例如下:</span></strong> 
            </div> 
            <br> 
            <strong><span style="color:#444444;"><span style="color:#999988;">// Returns an iterator for this table.&nbsp;&nbsp;It is the client's</span><span style="color:#999988;">// responsibility to delete the iterator when it is done with it,</span><span style="color:#999988;">// and it must not use the iterator once the GargantuanTable object</span><span style="color:#999988;">// on which the iterator was created has been deleted.</span><span style="color:#999988;">//</span><span style="color:#999988;">// The iterator is initially positioned at the beginning of the table.</span><span style="color:#999988;">//</span><span style="color:#999988;">// This method is equivalent to:</span><span style="color:#999988;">//&nbsp; &nbsp; Iterator* iter = table-&gt;NewIterator();</span><span style="color:#999988;">//&nbsp; &nbsp; iter-&gt;Seek("");</span><span style="color:#999988;">//&nbsp; &nbsp; return iter;</span><span style="color:#999988;">// If you are going to immediately seek to another place in the</span><span style="color:#999988;">// returned iterator, it will be faster to use NewIterator()</span><span style="color:#999988;">// and avoid the extra seek.</span>Iterator* GetIterator() const;</span></strong> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">但也要避免罗罗嗦嗦, 或做些显而易见的说明. 下面的注释就没有必要加上 “returns false otherwise”, 因为已经暗含其中了:</span></strong> 
            </div> 
            <br> 
            <strong><span style="color:#444444;"><span style="color:#999988;">// Returns true if the table cannot hold any more entries.</span>bool IsTableFull();</span></strong> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">注释构造/析构函数时, 切记读代码的人知道构造/析构函数是干啥的, 所以 “destroys this object” 这样的注释是没有意义的. 注明构造函数对参数做了什么 (例如, 是否取得指针所有权) 以及析构函数清理了什么. 如果都是些无关紧要的内容, 直接省掉注释. 析构函数前没有注释是很正常的.</span></strong> 
            </div> &nbsp; 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">函数定义:</span></strong> 
            </div> 
            <blockquote> 
             <div style="margin-left:0px;"> 
              <strong><span style="color:#444444;">每个函数定义时要用注释说明函数功能和实现要点. 比如说说你用的编程技巧, 实现的大致步骤, 或解释如此实现的理由, 为什么前半部分要加锁而后半部分不需要.</span></strong> 
             </div> 
             <div style="margin-left:0px;"> 
              <strong><span style="color:#444444;">不要 从 .h 文件或其他地方的函数声明处直接复制注释. 简要重述函数功能是可以的, 但注释重点要放在如何实现上.</span></strong> 
             </div> 
            </blockquote> 
           </div> <br><strong>7.5. 变量注释</strong> 
           <div style="margin-left:0px;"> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">通常变量名本身足以很好说明变量用途. 某些情况下, 也需要额外的注释说明.</span></strong> 
            </div> &nbsp; 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">类数据成员:</span></strong> 
            </div> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">每个类数据成员 (也叫实例变量或成员变量) 都应该用注释说明用途. 如果变量可以接受 NULL 或 -1 等警戒值, 须加以说明. 比如:</span></strong> 
            </div> 
            <br> 
            <strong><span style="color:#444444;"><strong>private</strong>:&nbsp; &nbsp;&nbsp;<span style="color:#999988;">// Keeps track of the total number of entries in the table.</span>&nbsp; &nbsp;&nbsp;<span style="color:#999988;">// Used to ensure we do not go over the limit. -1 means</span>&nbsp; &nbsp;&nbsp;<span style="color:#999988;">// that we don't yet know how many entries the table has.</span>&nbsp; &nbsp;&nbsp;<strong>int</strong>&nbsp;num_total_entries_;</span></strong> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">全局变量:</span></strong> 
            </div> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">和数据成员一样, 所有全局变量也要注释说明含义及用途. 比如:</span></strong> 
            </div> 
            <br> 
            <strong><span style="color:#444444;"><span style="color:#999988;">// The total number of tests cases that we run through in this regression test.</span><strong>const</strong>&nbsp;<strong>int</strong>&nbsp;kNumTestCases =&nbsp;6;</span></strong> 
           </div> <br><strong>7.6. 实现注释</strong> 
           <div style="margin-left:0px;"> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">对于代码中巧妙的, 晦涩的, 有趣的, 重要的地方加以注释.</span></strong> 
            </div> &nbsp; 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">代码前注释:</span></strong> 
            </div> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;">巧妙或复杂的代码段前要加注释. 比如:</span></strong> 
            </div> 
            <br> 
            <strong><span style="color:#444444;"><span style="color:#999988;">// Divide result by two, taking into account that x</span><span style="color:#999988;">// contains the carry from the add.</span><strong>for</strong>&nbsp;(<strong>int</strong>&nbsp;i =&nbsp;0; i &lt; result-&gt;size(); i++) {&nbsp; &nbsp; x = (x &lt;&lt;&nbsp;8) + (*result)<em>;&nbsp; &nbsp; (*result)<em>&nbsp;= x &gt;&gt;&nbsp;1;&nbsp; &nbsp; x &amp;=&nbsp;1;}</em></em></span></strong> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;"><em><em>行注释:</em></em></span></strong> 
            </div> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;"><em><em>比较隐晦的地方要在行尾加入注释. 在行尾空两格进行注释. 比如:</em></em></span></strong> 
            </div> 
            <br> 
            <strong><span style="color:#444444;"><em><em><span style="color:#999988;">// If we have enough memory, mmap the data portion too.</span>mmap_budget =&nbsp;max&lt;int64&gt;(0, mmap_budget - index_-&gt;length());<strong>if</strong>&nbsp;(mmap_budget &gt;= data_size_ &amp;&amp; !<span style="color:#445588;"><strong>MmapData</strong></span>(mmap_chunk_bytes, mlock))&nbsp; &nbsp;&nbsp;<strong>return</strong>;&nbsp;&nbsp;<span style="color:#999988;">// Error already logged.</span></em></em></span></strong> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;"><em><em>注意, 这里用了两段注释分别描述这段代码的作用, 和提示函数返回时错误已经被记入日志.</em></em></span></strong> 
            </div> &nbsp; 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;"><em><em>如果你需要连续进行多行注释, 可以使之对齐获得更好的可读性:</em></em></span></strong> 
            </div> 
            <br> 
            <strong><span style="color:#444444;"><em><em><span style="color:#445588;"><strong>DoSomething</strong></span>();&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;<span style="color:#999988;">// Comment here so the comments line up.</span><span style="color:#445588;"><strong>DoSomethingElseThatIsLonger</strong></span>();&nbsp;&nbsp;<span style="color:#999988;">// Comment here so there are two spaces between</span>&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;<span style="color:#999988;">// the code and the comment.</span>{&nbsp;<span style="color:#999988;">// One space before comment when opening a new scope is allowed,</span>&nbsp;&nbsp;<span style="color:#999988;">// thus the comment lines up with the following comments and code.</span>&nbsp;&nbsp;<span style="color:#445588;"><strong>DoSomethingElse</strong></span>();&nbsp;&nbsp;<span style="color:#999988;">// Two spaces before line comments normally.</span>}</em></em></span></strong> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;"><em><em>NULL, true/false, 1, 2, 3…:</em></em></span></strong> 
            </div> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;"><em><em>向函数传入 NULL, 布尔值或整数时, 要注释说明含义, 或使用常量让代码望文知意. 例如, 对比:</em></em></span></strong> 
            </div> &nbsp; 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;"><em><em>Warning</em></em></span></strong> 
            </div> 
            <br> 
            <strong><span style="color:#444444;"><em><em><strong>bool</strong>&nbsp;success = CalculateSomething(interesting_value,&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;10,&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;false,&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;NULL);&nbsp;&nbsp;<span style="color:#999988;">// What are these arguments??</span></em></em></span></strong> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;"><em><em>和:</em></em></span></strong> 
            </div> 
            <br> 
            <strong><span style="color:#444444;"><em><em><strong>bool</strong>&nbsp;success = CalculateSomething(interesting_value,&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;10,&nbsp; &nbsp;&nbsp;&nbsp;<span style="color:#999988;">// Default base value.</span>&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;false,&nbsp;&nbsp;<span style="color:#999988;">// Not the first time we're calling this.</span>&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;NULL);&nbsp;&nbsp;<span style="color:#999988;">// No callback.</span></em></em></span></strong> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;"><em><em>或使用常量或描述性变量:</em></em></span></strong> 
            </div> 
            <br> 
            <strong><span style="color:#444444;"><em><em><strong>const</strong>&nbsp;<strong>int</strong>&nbsp;kDefaultBaseValue =&nbsp;10;<strong>const</strong>&nbsp;<strong>bool</strong>&nbsp;kFirstTimeCalling =&nbsp;false;Callback *null_callback =&nbsp;NULL;<strong>bool</strong>&nbsp;success = CalculateSomething(interesting_value,&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp; kDefaultBaseValue,&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp; kFirstTimeCalling,&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp;&nbsp; &nbsp; null_callback);</em></em></span></strong> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;"><em><em>不允许:</em></em></span></strong> 
            </div> 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;"><em><em>注意 永远不要 用自然语言翻译代码作为注释. 要假设读代码的人 C++ 水平比你高, 即便他/她可能不知道你的用意:</em></em></span></strong> 
            </div> &nbsp; 
            <div style="margin-left:0px;"> 
             <strong><span style="color:#444444;"><em><em>Warning</em></em></span></strong> 
            </div> 
            <br> 
            <strong><span style="color:#444444;"><em><em><span style="color:#999988;">// 现在, 检查 b 数组并确保 i 是否存在,</span><span style="color:#999988;">// 下一个元素是 i+1.</span>...&nbsp; &nbsp;&nbsp; &nbsp;&nbsp;&nbsp;<span style="color:#999988;">// 天哪. 令人崩溃的注释.</span></em></em></span></strong> 
           </div> <br><em><em><strong>7.7. 标点, 拼写和语法</strong></em></em> 
           <div style="margin-left:0px;"> 
            <div style="margin-left:0px;"> 
             <em><em><strong><span style="color:#444444;">注意标点, 拼写和语法; 写的好的注释比差的要易读的多.</span></strong></em></em> 
            </div> &nbsp; 
            <div style="margin-left:0px;"> 
             <em><em><strong><span style="color:#444444;">注释的通常写法是包含正确大小写和结尾句号的完整语句. 短一点的注释 (如代码行尾注释) 可以随意点, 依然要注意风格的一致性. 完整的语句可读性更好, 也可以说明该注释是完整的, 而不是一些不成熟的想法.</span></strong></em></em> 
            </div> 
            <div style="margin-left:0px;"> 
             <em><em><strong><span style="color:#444444;">虽然被别人指出该用分号时却用了逗号多少有些尴尬, 但清晰易读的代码还是很重要的. 正确的标点, 拼写和语法对此会有所帮助.</span></strong></em></em> 
            </div> 
           </div> <br><em><em><strong>7.8. TODO 注释</strong></em></em> 
           <div style="margin-left:0px;"> 
            <div style="margin-left:0px;"> 
             <em><em><strong><span style="color:#444444;">对那些临时的, 短期的解决方案, 或已经够好但仍不完美的代码使用 TODO 注释.</span></strong></em></em> 
            </div> &nbsp; 
            <div style="margin-left:0px;"> 
             <em><em><strong><span style="color:#444444;">TODO 注释要使用全大写的字符串 TODO, 在随后的圆括号里写上你的大名, 邮件地址, 或其它身份标识. 冒号是可选的. 主要目的是让添加注释的人 (也是可以请求提供更多细节的人) 可根据规范的 TODO格式进行查找. 添加 TODO 注释并不意味着你要自己来修正.</span></strong></em></em> 
            </div> 
            <em><em><strong><span style="color:#444444;">// TODO(<a href="mailto:kl@gmail.com" rel="nofollow">kl@gmail.com</a>):&nbsp;<strong>Use</strong>&nbsp;a&nbsp;<span style="color:#dd1144;">"*"</span>&nbsp;here&nbsp;<strong>for</strong>&nbsp;concatenation operator.// TODO(Zeke)&nbsp;<strong>change</strong>&nbsp;this&nbsp;<strong>to</strong>&nbsp;<strong>use</strong>&nbsp;relations.</span></strong></em></em> 
            <div style="margin-left:0px;"> 
             <em><em><strong><span style="color:#444444;">如果加 TODO 是为了在 “将来某一天做某事”, 可以附上一个非常明确的时间 “Fix by November 2005”), 或者一个明确的事项 (“Remove this code when all clients can handle XML responses.”).</span></strong></em></em> 
            </div> 
           </div> <br><em><em><strong>7.9. 弃用注释</strong></em></em> 
           <div style="margin-left:0px;"> 
            <div style="margin-left:0px;"> 
             <em><em><strong><span style="color:#444444;">通过弃用注释（DEPRECATED comments）以标记某接口点（interface points）已弃用。</span></strong></em></em> 
            </div> &nbsp; 
            <div style="margin-left:0px;"> 
             <em><em><strong><span style="color:#444444;">您可以写上包含全大写的 DEPRECATED 的注释，以标记某接口为弃用状态。注释可以放在接口声明前，或者同一行。</span></strong></em></em> 
            </div> 
            <div style="margin-left:0px;"> 
             <em><em><strong><span style="color:#444444;">在 DEPRECATED 一词后，留下您的名字，邮箱地址以及括号补充。</span></strong></em></em> 
            </div> 
            <div style="margin-left:0px;"> 
             <em><em><strong><span style="color:#444444;">仅仅标记接口为 DEPRECATED 并不会让大家不约而同地弃用，您还得亲自主动修正调用点（callsites），或是找个帮手。</span></strong></em></em> 
            </div> 
            <div style="margin-left:0px;"> 
             <em><em><strong><span style="color:#444444;">修正好的代码应该不会再涉及弃用接口点了，着实改用新接口点。如果您不知从何下手，可以找标记弃用注释的当事人一起商量。</span></strong></em></em> 
            </div> 
           </div> <br><em><em><strong>译者 (YuleFox) 笔记</strong></em></em> 
           <div style="margin-left:0px;"> 
            <ul style="margin-left:14px;"> 
             <li><em><em><strong><span style="color:#444444;">关于注释风格，很多 C++ 的 coders 更喜欢行注释, C coders 或许对块注释依然情有独钟, 或者在文件头大段大段的注释时使用块注释;</span></strong></em></em></li> 
             <li><em><em><strong><span style="color:#444444;">文件注释可以炫耀你的成就, 也是为了捅了篓子别人可以找你;</span></strong></em></em></li> 
             <li><em><em><strong><span style="color:#444444;">注释要言简意赅, 不要拖沓冗余, 复杂的东西简单化和简单的东西复杂化都是要被鄙视的;</span></strong></em></em></li> 
             <li><em><em><strong><span style="color:#444444;">对于 Chinese coders 来说, 用英文注释还是用中文注释, it is a problem, 但不管怎样, 注释是为了让别人看懂, 难道是为了炫耀编程语言之外的你的母语或外语水平吗；</span></strong></em></em></li> 
             <li><em><em><strong><span style="color:#444444;">注释不要太乱, 适当的缩进才会让人乐意看. 但也没有必要规定注释从第几列开始 (我自己写代码的时候总喜欢这样), UNIX/LINUX 下还可以约定是使用 tab 还是 space, 个人倾向于 space;</span></strong></em></em></li> 
             <li><em><em><strong><span style="color:#444444;">TODO 很不错, 有时候, 注释确实是为了标记一些未完成的或完成的不尽如人意的地方, 这样一搜索, 就知道还有哪些活要干, 日志都省了.</span></strong></em></em></li> 
            </ul> 
           </div> </td> 
         </tr> 
        </tbody> 
       </table> 
      </div> 
     </div> 
    </div> </td> 
  </tr> 
 </tbody> 
</table>