The following documentation defines the means by which code will be commented and the types of documentation that will be produced. It should be noted that the Programming Style Guide contains its own guide to general commenting practice. Should this document and the Style Guide conflict when it pertains to commenting code, this document will take precedence. Please notify the Project Lead of any discrepancies between this document and the Style Guide so that they may be addressed.

Comments

Classes

• When building a class for the FN SDK, a <summary> tag will be written to describe the general purpose of the class.
  

  /// <summary>
  /// This is an example of a summary tag
  /// </summary>
  public class ExampleClass {}

  • Should additional information be needed to describe a class beyond a general purpose (for instance, possible use cases or items to keep in mind when using the class, a <remarks> tag will be used to avoid an overly verbose summary
    

    /// <summary>
    /// This is a brief summary
    /// </summary>
    /// <remarks>
    /// This is a lot more text that is acceptable within the confines of a remarks class.
    /// Here is another line of text for good measure
    /// And why not, here's a third line of text
    /// </remarks>
    public class ComplicatedClass {}

  • Should the class inherit from another class or implement an interface, a <see> tag will be use to link generated documentation to the appropriate base class/interface
    

    /// <summary>
    /// This is an example of a derived class with a see tag.
    /// <see cref="ExampleClass"/>
    /// </summary>
    public class DerivedExampleClass : ExampleClass {}

Methods

• When building a public method:

  • A <summary> tag will be written to describe the purpose for the method

  • A <param> tag will be written to describe each parameter within the public function
    

    /// <param name="left">
    /// The left operand of the addition.
    /// </param>
    /// <param name="right">
    /// The right operand of the addition.
    /// </param>
    public static int Add(int left, int right)
    {
        if ((left == int.MaxValue && right > 0) || (right == int.MaxValue && left > 0))
            throw new System.OverflowException();
    
        return left + right;
    }

  • A <returns> tag will be used to describe the return value of the method where applicable

    • Use common language when describing return values.
      ❌

      <returns>Returns an int</returns>
      public int GetAverage(int x, int y)
      {
        return (x+y)/2;
      }

      ✅

      <returns>Returns the average of two integers</returns>
      public int GetAverage(int x, int y)
      {
        return (x+y)/2;
      }

• When building a private method, no <summary> tagged comment is required. However, it is highly recommended that a genera,l non-xml tag be at least written to describe the nature of a private method should it’s purpose not be immediately apparent.

• If a method (public or private) can throw an exception, the exception tag will be used to document what types of exceptions the method can be expected to throw
  

  /// <exception cref="System.OverflowException">
  /// Thrown when one parameter is max and the other
  /// is greater than 0.</exception>
  public static double Add(double a, double b)
  {
      // If any parameter is equal to the max value of an integer
      // and the other is greater than zero
      if ((a == double.MaxValue && b > 0) 
          || (b == double.MaxValue && a > 0))
      {
          throw new System.OverflowException();
      }
  
      return a + b;
  }

Enumerations

• Enumerations will have a general comment to describe the general purpose of the enumerations as a whole

Miscellaneous

While example code itself is not required, should example code be included, an <example> and <code> block should be used.

/// <example>
/// <code>
/// int c = Math.Add(4, 5);
/// if (c > 10)
/// {
///     Console.WriteLine(c);
/// }
/// </code>
/// </example>
public static int Add(int left, int right)
{
    if ((left == int.MaxValue && right > 0) || (right == int.MaxValue && left > 0))
        throw new System.OverflowException();

    return left + right;
}