summary(サマリー)を書こう

はじめに

職場で「summary(サマリー)をちゃんと書こう」という話が出ました。

公式ページによると多くのタグがありますが、
とりあえず、使いそうなものをピックアップしました。

• summary
• remarks
• param
• returns
• exception

サンプル

/// <summary>
/// 文字列の先頭から指定した文字数の文字列を返します。
/// </summary>
/// <remarks>
/// lengthが0未満の場合：ArgumentException<br/>
/// strがnullの場合：null<br/>
/// lengthが0の場合：string.Empty<br/>
/// lengthが文字数以上の場合：str
/// </remarks>
/// <param name="str">文字列</param>
/// <param name="length">文字数</param>
/// <returns>取得した文字列</returns>
/// <exception cref="ArgumentException">lengthが0未満の場合</exception>
public static string Left(string str, int length)
{
    if (length < 0) throw new ArgumentException("引数'length'は0以上でなければなりません。");
    if (str == null) return null;
    if (length == 0) return string.Empty;
    if (str.Length <= length) return str;

    return str.Substring(0, length);
}

マウスカーソルを当てるとこんな感じになります。