スポンサーリンク

コードが書ける!数式が書ける!AAが書ける!スタンプが貼れる!

無料の匿名掲示板型SNS「このはちゃんねる

新規会員募集中!

プログラミングの「良いコメント」について考える

306, 2020-02-23

目次

プログラミングのコメントの良し悪し

プログラミングをしているとこういう話を聞くことが多いです。
それは、

  • コメントを書いたほうが良い

という話です。
じっさい、プログラミングではコメントを書いたほうが良いと言われています。
例外として、コメントを一切書かないルールのプロジェクトもあるそうですが……。

この記事では、プログラミングにおけるコメントの良し悪しについて考えてみたいと思います。
具体的には↓のとおりです。

  • 悪いコメントとは?
  • 良いコメントとは?

悪いコメントとは?

逆説的に考えてみたいと思うので、まずは「悪いコメント」について考えてみましょう。
「悪いコメント」の定義は難しいですが、この記事では↓のように定義することにします。

  • 必要のないところに書いている
  • 5W2Hが不足している
  • コメントと内容が違っている

まずは「必要のないところに書いている」についてです。

そのコメント、本当に必要ですか?

「必要のないコメント」というのはどういうものでしょうか。
↓の擬似コードを見てください。

func initSystem() {
    // defaultデーターベースから読み込み
    db, err = loadDatabaseFrom("default")
    if err != nil {
        return err
    }

    // DBからオブジェクト群を作成
    err = createObjectsFrom(db)
    if err != nil {
        return err
    }

    // 正常終了
    return nil
}

ひとつひとつ見ていきます。まず、関数の最初のほうのコメントです。

    // defaultデーターベースから読み込み
    db, err = loadDatabaseFrom("default")
    if err != nil {
        return err
    }

果たして「defaultデーターベースから読み込み」というコメントは必要でしょうか?
loadDatabaseFromという関数名からこのコメント内容は察知できるので、このコメントは冗長と言えます。
次のオブジェクト群を作成している所も同じです。

    // DBからオブジェクト群を作成
    err = createObjectsFrom(db)
    if err != nil {
        return err
    }

これもcreateObjectsFromという関数名からコメントに書かれている内容は察知できます。よって冗長と言えます。
最後のコメントを見てみます。

    // 正常終了

これに至っては何のためのコメントなのかすらよくわかりません。
これらのコメントを削除すると先程のコードは↓のようになります。

func initSystem() {
    db, err = loadDatabaseFrom("default")
    if err != nil {
        return err
    }

    err = createObjectsFrom(db)
    if err != nil {
        return err
    }

    return nil
}

コメントがあるときに比べてみてどうでしょうか。コードから処理内容は察知できるので、コメントが無くても読むのには支障がないように見えます。
更にいうと、このコードにおいてコメントが必要なところは関数のところです。下のようにコメントを書けば完璧と言えるかもしれません。

/**
 * defaultデータベースを読み込んでオブジェクト群を作成し、システムを初期化する
 */
func initSystem() {

この場合、initSystemという関数名から関数の具体的な処理内容はわかりません。
そのためコメントで処理内容を補足するのはコメントの本来の役割にかなっていると言えます。

5W2Hが不足している

5W2Hとは↓のような項目です。

  • Who ... だれが
  • What ... なにを
  • When ... いつ
  • Where ... どこで
  • Why ... どうして
  • How ... どのように
  • How many ... どのぐらいやったか

ニュース記事の作成などに用いられる物事を正確に伝えるための条件です。
プログラミングのコメントでも、物事を正確に伝えることが求められるため、この5W2Hを適用するのは正解と言えます。

たとえば↓の擬似コードを見てみましょう。

func updateSystem() {
    key = getInputKey()

    switch key {
    case KEY_ENTER:
        // BGMをストップしてからコマンドを挿入する
        stopBGM()
        command = getCommand()
        insertCommand(command)
        playBGM()
    }
}

BGMをストップしてからコマンドを挿入する」というコメントがありますが、このコメントには5W2Hが不足しています。
具体的には「Why ... どうして」の項目が抜けているため、なぜBGMをストップしなくてはならないのか開発者はわかりません。
このコメントは↓のように改善することができます。

func updateSystem() {
    key = getInputKey()

    switch key {
    case KEY_ENTER:
        // コマンドの挿入前にBGMをストップしてからコマンドを挿入する
        // BGMを鳴らしながらコマンドを挿入すると、BGMが乱れるバグが起きた
        // このバグは現在調査中だが原因がわかっていない
        // そのため応急的にここで対処することにする
        // 2020/02/23
        stopBGM()
        command = getCommand()
        insertCommand(command)
        playBGM()
    }
}

↑のようにすればバグへの応急処置的なコードなんだということがわかりますし、バグが直ったらコードを改変し、コメントを削除してもいいこともわかります。
日付についてはバージョン管理ソフトのコミットのログを見れば、いつ挿入したコメントかはわかるので、ここでは冗長かもしれません。
しかし、日付があったほうが「いつ」がわかるためパッと見は見やすいでしょう。

コメントと内容が違っている

厄介なコメントの例です。
これは、コメントが害悪なものになってしまっているパターンです。
つまり、コメントの内容と実際の処理内容が異なっていて、やってることがチグハグになってしまっているわけです。
開発者はコメントを読みますが、コメントが書かれた当時、コメントの内容が本来の姿だったのか、それともコメントを無視した実際の実装が本来の姿だったのかわからなくなります。

例えば↓のコードを見てみましょう。

func slideBackground() {
    // 負の方向にスライドしてバックグラウンドを更新する
    slide = slides[slidesIndex++]
    setBackground(slide)
}

負の方向にスライドしてバックグラウンドを更新する」と書かれていますが、実際の処理では正の方向にスライドしています。
本来はどっちが正解だったのか、このコメントとコードを見ただけでは開発者はわかりません。
更にいうと、このコメントは本来は必要のないコメントです。

勘弁して

ここらへんが「コメントを書かない」という人たちの理由かもしれません。
コメントはこのように害悪化することがあるので、扱いが意外とデリケートです。

繊細なのね

良いコメントとはなにか?

先に悪い例を上げてきました。
この反対が良いコメントだということになります。
つまり、

  • 必要なところに書かれている
  • 5W2Hが足りている
  • コメントと内容が合っている

ということになります。
これらは、こうやって見るとどれも当たり前のことですが、実際の開発では往々にしてこれらの規範から外れることがあります。
開発者は万能ではないので、そういった事態が起こります。
これを防ぐにはコードレビューなどが有用かもしれません。

おわりに

いかがでしたでしょうか。
今回はプログラミングにおける良いコメントと悪いコメントについて考えてみました。
優秀な開発者でも気を抜くと悪いコメントを書きがちです。
困ったら5W2Hを思い出すようにしましょう。

だれが、なにを、いつ、どこで、どうして、どのように、どれぐらい……

おしまい

投稿者名です。64字以内で入力してください。

必要な場合はEメールアドレスを入力してください(全体に公開されます)。

投稿する内容です。

スポンサーリンク

スポンサーリンク

スポンサーリンク

スポンサーリンク