俺の場合、ソースコードから語りかけにくるよね。 By ローランド泉

はじめに

PHPに限った話ではないですが、コメントってそうそういらないと思うんです。
コメントがいるのはあくまで「コードでは伝わりきらない部分を伝えるため」だと思うんです。

なので、全くいらないわけじゃないし、こういう話をすると永遠に答え出ないと思うんです。
でも、なんでこんなコメント頑張って付けてるのかなって思う事が多々あるので、それを個人的にまとめてみました。

※今回はPHPだけに絞って考えてみました。
※今まで自分も漠然と付けてきた部分もあるので、自分への戒めのための記事でもあ－－－るのです。なんて日だ！！

PHPの標準コーディング規約

色々ありますが、「PSR」などを読んでおけばよいかと。
⇒フレームワークが何を採用しているかは重要なので、あなたが使用しているフレームワークが何基準なのかは押さえておきましょう。

コメントいらない思想

冒頭でも言いましたが、僕はコメントいらない思想です。
っていうのも、僕の師匠がコメントいらない思想だったのは大きいですが。

厳密にはコメントは必要なんですが、コメントいる思想を持ってしまうとコメントに頼ってしまって綺麗にコードを書こうと意識しません。
実際に動くのはソースコードなので、これでは元も子もありません。

ってことで、コメントいらない思想を持った僕の観点でグダグダ書いていきます。

PHPのコメントいらないパターン

まずはサンプルを

sample.php

    /**
     * hogeを取得する
     *
     * @param array $hoge
     * @return string
     */
    public function fetchHoge($hoge)
    {
        $hoge2 = null;

        // $hogeを使った何かしらの処理

        return $hoge2
    }

渡されてきた「hoge」を使って何かしら処理をした後、「hoge2」を返すという意味不明な関数です。
まあ、細かい所は無視してください。
以降、このサンプルで説明します。

いらないパターンその1：コメントに記載されている「型」

sample.php

    /**
     * hogeを取得する
     *
     * @param array $hoge　←ここの「array」
     * @return string      ←ここの「string」
     */

いやーーーーーーーー、いらない。
超いらない。
どれくらいいらないかと言うと、女性に年齢聞いて「何歳だと思います？」って質問で質問を返されるくらいいらない。

sample.php

    /**
     * hogeを取得する
     *
     * @param $hoge ←「array」いらん
     * @return      ←「string」いらん
     */
    public function fetchHoge(array $hoge): string // ←You, ここに型書いちゃいなよ
    {
        $hoge2 = null;

        // $hogeを使った何かしらの処理

        return $hoge2
    }

あんなコメントを書くくらいならこうでしょう。
タイプヒンティングってやつですが、これはPHPのバージョンが7.0以上じゃないと使えないやつとかもあります。

ここで言いたいのは、コメントに書くくらいならコードで保証しましょう。
コメントなんて動作しているものではないので完全に信用なんてできません。

僕ならどこぞの誰が書いたかも分からない~~クソエンジニア~~素晴らしいエンジニアのソースコードなんて信じません。

いらないパターンその2：コメントに記載されている「変数名」

sample.php

    /**
     * hogeを取得する
     *
     * @param array $hoge　←ここの「$hoge」
     * @return string
     */

いやーーーーーーーー、いらない。
これはなんですか？
変数名が変わったらコメントも変えるんですか？

凄くイケてない。
どれくらいイケてないかと言うと、おしゃれなスーツ着てるのにスマホ見ながらクチャクチャ食事してる見た目だけ意識高そうなサラリーマン位イケてない。

sample.php

    /**
     * hogeを取得する
     *
     * @param array   ←「$hoge」いらん
     * @return string
     */
    public function fetchHoge($hoge)
    {
        $hoge2 = null;

        // $hogeを使った何かしらの処理

        return $hoge2
    }

変数名なんてコード見たら分かります。
見て分かることをコメントに書くことほど無駄なことはありません。

パターン1,2をまとめると...

sample.php

    /**
     * hogeを取得する
     *
     * @param
     * @return
     */
    public function fetchHoge(array $hoge): string
    {
        $hoge2 = null;

        // $hogeを使った何かしらの処理

        return $hoge2
    }

こうなると、もはや「param」と「return」の記載自体いらなくなりますが、もし仮にこれを消すと、そもそも「もうコメントいらなくね？」ってなります。
勿論それでもよいのですが、現場では「param」と「return」を書くケースはそれなりに多い気がします。
⇒あくまで僕の感覚。

なので、「param」と「return」を残しつつ、いい感じにしていくのがベストとします(勝手に)。

いい感じにコメントを書くとこんな感じかな？

sample.php

    /**
     * hogeを取得する
     *
     * @param  ほげ～(本来は、変数の説明を日本語で分かりやすく記載する)
     * @return ほげ～2(本来は、変数の説明を日本語で分かりやすく記載する)
     */
    public function fetchHoge(array $hoge): string
    {
        $hoge2 = null;

        // $hogeを使った何かしらの処理

        return $hoge2
    }

コメントを書くと決めた以上、最小限に、かつ日本語で説明を書いてあげるのがベストな気がします。
これであれば、あくまで説明なので2重メンテ(変数名を変えたらコメントの方も変えるみたいなこと)にもなりません。
まあ、変数の役割などが変わってくるとあれですが、そこは

paramとかのコメントも書かない
仕方ないとして今回のようなコメントの書き方にする

かを決めるべきでしょうね。

おまけ

厳格な型付けは必要か？

タイプヒンティングは、厳密には「弱い型付け」と呼ばれる状態です。
例えば、引数に「int $hoge」と宣言されているものがあるとして、ここに「"123"」という文字列を渡すと、PHPは限界まで頑張って暗黙の型変換を行います。
これを良しとしない方法として、以下を記載することがあります。

declare(strict_types=1);

ただ、個人的にはそこまでしなくてもいいんじゃないかと思います。
いや、実はやりたいんですが、毎回これを書くのがダサい。すごくダサい。

そう、もはやこれは好みの問題なのです。
いや、もはやこれは愛の問題なのです。

これもすごくダサくない？

    /**
     * hogeを取得する
     *
     * @return void
     */

これはさっきの話で「void」をタイプヒンディングでつければいいんですが、そこではなくて、「そもそも返すものないのにreturnいらんやろ」って話です。
要はコメントが過剰に頑張っちゃってるって話です。
どれくらい過剰かって言うと、インフルエンザ流行ってる時期に冷えピタおでこに貼りながら出勤してくるお馬鹿さんくらい過剰に頑張っています。

PHPにタイプヒンティングってどうなのよ？っていう声

PHPは型がない言語として認識されています。
メリットでよく言われるのは「自由度が高い」こと。

型なし言語をゴリゴリ使っている人からすると、タイプヒンティングは自由度を殺すように思えるかもしれません。
僕も最初はそう思っていましたが、そもそも「型なし」だという事自体が間違っています。
型はないのではなく、型が暗黙的に解釈されているのであって、型はあるのです。

つまり、

型はあるけど型はない
型はないけど型はある

のです。

そうなると、元々あった型を明示的に書いてあげてるわけですから、「何ら問題はないよね？」ってことになります。
どれくらい問題がないかって言うと、旅行に行ってわざわざお土産を買ってこなくても問題ないよね？ってくらい問題がない。

PHPDocumentorとかいらんやろ

「param」とかのコメントってちゃんと書いておくと、PHPDocumentorってやつで自動的にドキュメントを吐き出せるようです。
つまり、ここらへんちゃんと書いておかないとPHPDocumentorでは自動生成できないと思われます(使ったことないから知らん)。

じゃあここで疑問が出てくるわけです。
そもそもソースコードのドキュメントなんていりますか？
いや、いらない。

僕は元々Java屋さんですが、JavaDoc(でしたっけ？)なんて見たことない。
そんなん見るなら直接コード見るわ。

それに、ソースコードの設計書の前にちゃんとした設計書あるでしょ？
いらないいらない。

いらないものに対して頑張ってコメントをきれいに書いても、いらないものはいらない。
いらないものはどこまで行ってもいらないです。

※あくまで個人的な見解です。←ここ重要。テストに出ます。

おわりに

最後に素晴らしい俳句で締めたいと思います。

PHP書いてて本当に要らないなって思うコメント達

俺の場合、ソースコードから語りかけにくるよね。 By ローランド泉

はじめに

PHPの標準コーディング規約

コメントいらない思想

PHPのコメントいらないパターン

まずはサンプルを

いらないパターンその1：コメントに記載されている「型」

いらないパターンその2：コメントに記載されている「変数名」

パターン1,2をまとめると...

いい感じにコメントを書くとこんな感じかな？

おまけ

厳格な型付けは必要か？

これもすごくダサくない？

PHPにタイプヒンティングってどうなのよ？っていう声

PHPDocumentorとかいらんやろ

おわりに

コメントは、必要そうで、必要ない By ローランド泉