はじめに
C#というよりもVSCodeやVisualStudioのようなIDE向けのTipsのような気がしますが、これらのIDEではドキュメントコメント（XMLコメント）が使用できます。
ドキュメントコメントを付与しておくとIDE経由でメソッドの情報などを見ることができるようになるので、後々便利です。
また、昨今はAIが登場したことにより、既存コードの情報として記述しておくと入力時に返答の精度が上がると思います（たぶん）。
ドキュメントコメントとは
そもそもドキュメントコメントはどういうものかというと下記のようなスラッシュ３つから始まるコメントの記述のことです。
/// <summary>
/// パスの区切り文字を正規化します。
/// </summary>
/// <remarks>
/// - バックスラッシュ(\)をスラッシュ(/)に変換<br/>
/// - 連続する区切り文字(// や \\\ など)を単一のスラッシュ(/)に変換
/// </remarks>
/// <param name="path">正規化するパス文字列</param>
/// <returns>
/// 正規化されたパス文字列。<br/>
/// 入力がnullまたは空文字の場合は、入力値をそのまま返します。
/// </returns>
/// <example>
/// 以下のパスはすべて同じ文字列に正規化されます:
/// <code>
/// "Assets\\Path" -> "Assets/Path"
/// "Assets/Path" -> "Assets/Path"
/// "Assets//Path" -> "Assets/Path"
/// </code>
/// </example>
public static string NormalizePath(string path)
{
if (string.IsNullOrEmpty(path)) return path;
// すべての区切り文字を'/'に変換
path = path.Replace('\\', '/');
// 連続する'/'を単一の'/'に置換（複数回の置換で///なども対応）
while (path.Contains("//"))
{
path = path.Replace("//", "/");
}
return path;
}ここではXMLタグを使用することができ、summaryやreturns等を記述しておくことにより、下図のようにIDE上でメソッドにカーソルを合わせたときなどに詳細な情報が表示されるようになります。
先程の例はAIに追加させたものなので、かなり詳細に書かれていますが、通常使用する範囲ではsummary,param,returnsの３つを使えば十分だと思います。
/// <summary>
/// パスの区切り文字を正規化します。
/// </summary>
/// <param name="path">正規化するパス文字列</param>
/// <returns>
/// 正規化されたパス文字列。<br/>
/// 入力がnullまたは空文字の場合は、入力値をそのまま返します。
/// </returns>
public static string NormalizePath(string path)
{
if (string.IsNullOrEmpty(path)) return path;
// すべての区切り文字を'/'に変換
path = path.Replace('\\', '/');
// 連続する'/'を単一の'/'に置換（複数回の置換で///なども対応）
while (path.Contains("//"))
{
path = path.Replace("//", "/");
}
return path;
}その他使用可能なタグの説明については下記参照のこと
https://learn.microsoft.com/ja-jp/dotnet/csharp/language-reference/xmldoc/recommended-tags
書き方
メソッドの記述を先に完成させてから追加するのがおすすめです。
なお、中身は一旦空でも良いです。
必要な引数や関数名などを記述してからメソッドの一つ上の行にスラッシュを３つ「///」記述すると、このようなテンプレートを追加してくれるので、これを埋める形が書きやすいと思います。
/// <summary>
///
/// </summary>
/// <param name="Path"></param>
/// <returns></returns>ただ、最近はAIも登場してきましたので、（機密上の問題がなければ）コードを丸ごとAIに上げて「XMLコメントを付けて」とか「ドキュメントコメントを追加して」とかの指示を与えたほうが簡単だと思います。
さいごに
数日前に書いたコードの意味などどんどん忘れていきますので、内容を改めて思い出すコストというものは必ず発生します。
本来不要なコストをなるべく払わずにすむように、ドキュメントコメントをはじめとした適切なコメント付与は心がけていきたい所存です。
最後までお読みいただき、ありがとうございます！
コメント