Page Comparison

...

• 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
    

    Code Block
    /// <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.
      ❌

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

      ✅

      Code Block
      <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 generageneral, 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
  

  Code Block

  /// <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; }

...