The Elements of C# Style - Documentation

1. 一般原则

  1.1 为使用接口的人编写软件接口文档

      编写文档注释的首要目的是在服务的提供者(supplier)和客户(client)之间定义一种编码契约(programming contract)。与方法相关的文档应该描述该方法的调用者可依赖的行为的诸多方面，而不应该试图描述其实现细节。

  1.2 为维护者编写代码实现文档

      编写代码实现部分文档，好让别人可以维护和增强代码。总是假定会有完全不熟悉你的代码的人要阅读和理解你的代码。

  1.3 为维护者编写代码实现文档

     编写代码实现部分的文档，好让别人可以维护和增强代码。总是假定会有完全不熟悉你的代码的人要阅读和理解你的代码

  1.4 保持注释和代码同步

     修改代码时，也要确保更新相关注释。代码和文档以前构成软件产品，应对其同等重现。

  1.5 尽早编写软件元素的文档

    在实现之前或实现之中编写每个软件元素的文档，勿拖延至软件将近完成才编写。

  1.6 考虑全世界读者

  1.7 在每个文件的开始添加版权、授权许可和作者信息

  2.API

  2.1 尽量使用C#语言内构建的文档机制

    C#允许在源代码中嵌入XML注释，然后自动生成API文档。

  2.2 编写重要的前置条件、后置条件和不变条件的文档

  前置条件(precondition) 是一种条件判断，如果某个方法远行正常则它在该方法之前保持为真值。典型的前置条件可以限制方法参数的可接受值范围。

  后置条件(postcondition)是一种条件判断，如果某个方法远行正常，则它在该方法结束之后保持真值。典型的后置条件描述一个对象的状态，该对象应来自给定初始状态及调用参数来调用的方法。

  不变条件(invariant)是一种条件判断，对于某对象总保持为真值。典型的不变条件可能是现在表示在1到12之间的当前月份的一个整型字段。

  2.3 编写线程同步需求

  如果需要在多线程环境中使用，则应该在文档中写明线程安全级别。说明对象是否能在线程间共享，如果可以，则说明是否需要外部同步串行访问。完全线程安全的对象或方法使用期自身的同步机制，在多线程中保护内部状态。

  2.4 编写已知缺陷和不足

  标示并描述与类或方法有关的突出问题。指出存在的替代方案或解决方法。如果有可能，则说明何时可以解决这个问题。

  2.5 使用主动语态描述操作者，使用被动语态描述动作

   当操作者在场景中教为重要时，使用主动语态。

   当对象被操作时，或操作比操作者重要时，使用被动语态。

  2.6 当前称当前类的实例时，使用“this”.不用“the”

  当描述方法的目的或行为时，使用this而不用the来指称定义该方法的类的实例对象。

3 . 内部代码

 3.1 只在需要帮助别人理解代码的时候才添加内部注释。

 3.2 解释代码为什么要这么做

 3.3 避免使用C风格的注释块

 3.4 使用单行注释描述实现细节

  例如以下场合：

   特定变量或表达式的目的

   实现层面的设计决定

   复杂算法的来源资料

   缺陷的修正或变通方法

   以后可能做优化或加工的代码

   任何所知的问题、局限或缺陷

  3.5 避免使用行末注释

  3.6 在多重嵌套控制结构中标出结束花括号

for ( int i = 0 ...)
{
   for( int j =0 ...)
    {
      while( ! done)
        {
         if (...)
          {
            switch(...)
            {
                //...
            }//结束switch
          } //结束if
        }//结束while
     }//结束j
} //结束i

3.7 使用关键词标出待完成工作、未解决问题、错误和缺陷修正

   

// **FIX** - 添加刷新缓冲区代码
//TODO Jonh Smith 5/5/2005
//这些代码无法处理输入溢出内部缓冲区的情况
 while(everMoreInput)
{
//..
}

3.8 标出空语句

  

while((c =  reader.Read()) == ' ') ;
//空！