コードのコメントはシンタックスじゃなくセマンティクスを書こう

アンチパターン C#

コードの構造とか文法を一生懸命説明するシンタックスコメント職人が世の中に結構いるみたいです。

例えばこんなの

// ログを出力する
Log.WriteLine("ERROR", "Failed to hogehoge function.");
Log.WriteLine("ERROR", ex.ToString());

コード見ればわかるような、コードのシンタックスの説明を一生懸、何千何万と同じ内容を書いてるんですが、ログを出力しようとするたびに"//ログを出力する"…ってそんなの見れば分かりますよね。

しかも恐ろしい事に何千回も同じこと書いてるんですよ。完全一致検索で数千件引っかかるのでそれよりもっと大量にあることは確実です。ちなみに規約でコメントを強制しているわけではありません。

誰か、どこかに、そのクソコメントを書いていた時間をの工数を請求したと思うと胸が熱くなりますね。

以下、続きです。


このコメント意味有るんですかね？

public class HogeValodator
{
    // コンストラクタ
    public HogeValodator()
    {
    ...


見れば分かります。

// GUIの進捗を初期化する
GuiProgress.StepInit(8);

...

// 進捗を報告する
GuiProgress.StepAckTo(1);

...

// 進捗を報告する
GuiProgress.StepAckTo(2);

...

// 進捗を報告する
GuiProgress.StepAckTo(3);


インターネットのコピペか何かですか

// ダブルクリックイベントハンドラ
public void OnSingleClickEvHandler()
{


見れば分かります。

// アサート
Assert.AreEqual("Result", strVal);


見れば分かります。

// using
using System;


それは違います。

// #inclide <stdio.h>
using System;


見ればわかります。

public class Sample 
{
    /// <summary>
    /// ファイナライザ
    /// </summary>
    ~Sample() 
    {
        this.Dispose(false);
    }
}


シーシャープとかジーユーアイとかアイオーとかの仲間ですね。

public class Sample 
{
    /// <summary>
    /// ディスポーズ
    /// </summary>
    Dispose() 
    {
        this.Dispose(true);
    }
}


裏の裏は表？

// 実行できない場合trueを返します
public CanExecute()
{
    // 実際は実行できない場合falseが帰ってきました。


手作業なのにコードジェネレータがインストールされているのかな？

// ◆ 仕様書の1.1.2 ホゲホゲの処理
...

// ◆ 仕様書の1.1.3 ホゲホゲの処理
...

// ◆ 仕様書の1.1.4 ～ 1.1.7 までの処理


マジでやめてくれー！こんなの書かない方がマシです。

いや、こういうのって名前付けもタコなのが多いからこれでもこのクソコメントが無いと困るなんてケースもあります。中学生の英語忘れちゃったのかな？

こういったコード書く人って何年たっても変わらず無意味な同じコメントを何千何万と疑問を持たずにコミットしてくるんですよね。是非、『リファクタリング』だとか、『リーダブルコード』でも読んで自分のやっていることを顧みてほしいですね。

ちなみに、「見ればわかるコメントは書かない」とコーディング規約に書いたらコメントが一切かかれないブツを頂戴したこともあったのでなかなか厄介なのかもしれません。

特に、XMLコメントがクソだとドキュメント自動生成時の生成物の質もクソになるので膨大な未知のコードを分析する時にとっても大変です。

コメントにはシンタックス(構造)ではなくセマンティクス(論理的な意味/上位の仕様)を書くべきですね。