PHP
document
チーム開発
コメント
健康

PHPのコメントって何を書けばいいの?という人に役立つtips

1. コメントについて

プログラム内のコメントって意外と議論されていない気がするので投稿します。

ちなみに、以下の記事がコメントについてとても素晴らしくまとめてくれています。

上記記事と多少被りますが、私が個人的な経験上書くようにしているコメントや書くのをやめたコメントを紹介します。

また、いくつものレガシーコードを見てきた経験から、実際に見たよくないコメントの例を紹介します。

これを読んだ誰かの一助になったり、チームで話し合うきっかけになれば嬉しいです。

ちなみに、参考図書としては『リーダブルコード』がおすすめです。

55頁あたりからコメントについて触れています。

2. 私が経験上書くようにしているコメント

前提:クローズドな自社プロダクトを想定。ライセンスやコピーライトは省く。

ファイルコメント

<?php
/**
 * [ファイル内容説明]
 *
 */

  • @versionは経験則から言って、改修がかかった際に更新されない(忘れがち)です。そのため、joinしているプロジェクトの既存コードや改修履歴から空気を読んで付けたり付けなかったりします。
  • @sinceも同上。
  • 既存ファイルを改修した際は@linkを追記しています。
  • @authorは(私としては基本的にいらないという結論に至りましたが)チーム文化とプロジェクトの寿命などから書くべきかどうか考えると良いと思います。

2018/01/19追記
以下のようなご意見を頂戴しました。

@author はバージョン管理システムのコミットログを見ればわかるので、あまり書かないほうがいいと思います。

既存ファイルを改修した際は@linkを追記しています。

コミットログ見ればわかるし、コメントに残すべき内容ではないと思います。

@linkに関しては、頂戴したご意見の通り変更回数が多いファイルなどに毎回追記するとlinkが多くなってしまい不要なコストになってしまうこともありそうです。
私の場合はコミットコメントやブランチ名が適切でなく、コミットログを追うこと自体が辛い環境に身を置いていたので上記のような経験則になりましたが、頂戴したご意見の方が正しいかと思われます。

2018/02/27追記

私自身なんとなく@authorは書いたり書かなかったりしましたが、やはり書かない方が良いという結論に至り、ファイルコメントはファイルの概要説明だけでいいんじゃないかという結論に至りました。

公開ライブラリやモジュールなどで著作権表示をしたい場合はファイルコメントにつけるのがいいのかな、それ以外はいらないんじゃないかな、という結論です。


メソッドコメント

    /**
     * [簡潔な処理内容]
     * 
     * @param [型やクラス名] [引数の変数名]
     * @param [型やクラス名] [引数の変数名]
     * @return [型] [変数名] 変数名まで書かない派の人もいる。
     * @throws [Exceptionタイプ] [どんな時に投げられるかの説明]
     */
  • 複数の型をreturnするメソッドの場合は以下のようにしている。
    • 自分ではそもそも複数の型を返すメソッドは書かないようにしている。
 * @return [型] | [型]  [どういう時どっちが帰ってくるのか簡単に説明]

インラインコメント

  • 基本的に意図を明示する必要が見込まれる時のみ書く。
    • PSR-2にいい例があったので一部改変し転載。
    switch ($a) {
        case 0:
            break;
        case 1:
            // no break
        default:
            break;
    }

3. 本当にあった怖いコメント。アンチパターン

良いコメントを残すことがチームや本人に対する多大な貢献なのは間違いないです。

しかし、何がなんでもコメントを残せばいいということではなくて、悪いコメントは生産性を下げる要因になり得ます。

今まで実際に見てきたコメントのアンチパターンをいくつか紹介します。


e.g. 見ればわかることを説明するコメント

  • 二度同じことを書く必要はない。
    // $aと$bが同一だったら
    if ($a === $b) {

    }

    // idの配列
    $ids = [1,2,4,5];


e.g. 意味のないコメント

  • ほんのり可愛らしく個人的には嫌いじゃないですが、不要です。
    // foreachでぐ〜るぐる
    foreach ($array as $key => $value) {

    }


e.g. 内容と合っていないコメント

  • それ空文字じゃないです。
    // 空文字を入れて初期化
    $a = null;

e.g. それ命名でどうにかならないの?というコメント

  • 変数名を$usersとかメソッド名をfetchAllUsersとかそういう感じにすればいいんじゃないかと思います。
    // 全user配列
    $data = fetchAll();

e.g. いらないコードの説明をしているコメント

  • いらないなら$keyを書かなければいいです。コメントも必要なくなって一石二鳥です。
    // $keyは使わない
    foreach ($array as $key => $value) {

    }

4. 最後に

どんなコメントを残すか、改修する際はどうするのか、

どこまでドキュメントに書いてどんな部分をコメントとして残すのか、

ちゃんとチーム内で話し合ったり、ライブラリや本を読んで常識を知ったり、その上で更に自分で考えたりしましょう。

インターネッツに書いてあることと実際の現場で必要とされていることは得てして全く違ったりしますので、

確固たる意志で「自分はこうするんだ」というポリシーを持つまでの知識と根拠を得るか、

こうしていきましょうよ、とチームで共通認識を作っていくのがいいと思います。

なぜプログラムにコメントが必要なのか

結論から言うと、エンジニアが最も嫌う"無駄"が省けるから、だと思います。

私自身チーム開発を行ってきて、ちょっとした情報が欠けていることで処理の流れや意図を把握するのに苦労し、処理の意図を読み間違えたことからバグや要件との乖離を起こしてしまったことがあリます。

この問題を解決するために、コメントが必要になってくると思うのです。

大前提として、エンジニアはコードを読めます。

つまり、"コードが何をしているか"は読めばわかります。しかし、"なぜこのコードを記述したか"をコードから読み解くのは中々に難しいことです。

ドキュメントやチケット、コミットログがしっかりと整備されていれば解決できる問題かもしれません。しかしそれらがどこにあるか分からない、粒度がバラバラで何の参考にもならないという状況はよくあることです。

どこにあるか分からない、役に立つかもわからないドキュメントやログを探し、追う必要のない無駄なコードを読む時間はエンジニア個人にとってもチーム全体にとっても無駄なコストと言えるでしょう。

この問題の解決に貢献する二つのアプローチがあります。

  • "ドキュメント/チケット/コミットログの粒度を揃える"という組織/チーム体制的アプローチ。
  • "良いコメントを残す"というエンジニア個人ができるアプローチ。

つまり、良いコメントを残すと言う行為はエンジニア個人の意識と行動でチーム全体に貢献できる手軽な手段なのです。

それはチームにとってもエンジニア自身にとっても得になる行為です。

だからこそエンジニアは良いコメントを書くべきだと私は思うのです。