Whatを書くな。Whyを書け。

コメントを書くときのお話。

「What」のコメントとは

    public static void main(final String[] args) {

        final List<String> telList = Arrays.asList("090-1234-5678", "090 1928 3746", "09098765432");
        final List<String> result = formattedTel(telList);
    }

    public static List<String> formattedTel(final List<String> telList) {

        // 結果用のリストインスタンスを初期化
        final List<String> result = new ArrayList<>();

        // 電話番号リストの各要素に対して処理をする
        telList.forEach(tel -> {
            if (tel.contains("-")) {
                // 電話番号にハイフンが含まれている場合
                result.add(tel.replace("-", ""));
            } else if (tel.contains(" ")) {
                // 電話番号にスペースが含まれている場合
                result.add(tel.replace(" ", ""));
            } else {
                // 含まれていない場合
                result.add(tel);
            }
        });

        // 結果を返却
        return result;
    }

        // 結果用のリストインスタンスを初期化
        final List<String> result = new ArrayList<>();

変数名からも結果用とわかるし、new ArrayList<>()の意味をわざわざ説明する意味はない。

        // 電話番号リストの各要素に対して処理をする
        telList.forEach(tel -> {

これもforEachを説明しているだけ。

            if (tel.contains("-")) {
                // 電話番号にハイフンが含まれている場合

これもif文の条件を日本語化しているだけ。

他のコメントもどれもこれも、プログラムで表現されている内容を日本語に翻訳しているだけで、全く意味の無いコメントになっている。

プロジェクトによっては、統一性のためにこういったコメントも書く必要があるところもあるとは思うが、こういったコメントは見るのも書くのもしんどい。

また、コードを修正する際に、コメントも修正する必要があるかどうかを気にしなくてはならない。
これが大きなプロジェクトになると、コメントの修正漏れが多発し、コードとコメントで言ってることが違う！なんてことが起きる。

「Why」のコメントとは

    public static void main(final String[] args) {

        final List<String> telList = Arrays.asList("090-1234-5678", "090 1928 3746", "09098765432");
        final List<String> result = formattedTel(telList);
    }

    /**
     * 電話番号のフォーマットを、数字のみの形式に揃える。
     *
     * @param telList 電話番号リスト
     * @return フォーマットを揃えた電話番号リスト
     */
    public static List<String> formattedTel(final List<String> telList) {

        final List<String> result = new ArrayList<>();

        telList.forEach(tel -> {
            if (tel.contains("-")) {
                result.add(tel.replace("-", ""));
            } else if (tel.contains(" ")) {
                result.add(tel.replace(" ", ""));
            } else {
                // 既に数字のみで構成されている電話番号のため、文字列操作は何もしない
                result.add(tel);
            }
        });

        return result;
    }

    /**
     * 電話番号のフォーマットを、数字のみの形式に揃える。
     *

このJavadocだけで、他はコードを読みさえすれば理解できる。
さっきまでのあってもなくても意味のないコメントは無くなった。

                // 既に数字のみで構成されている電話番号のため、文字列操作は何もしない
                result.add(tel);

これは「What」の要素も含んでいるが、個人的にこのコメントは必要だと思っている。
なぜなら、第３者視点で考えた時に、「他の分岐と違って文字列操作が無いのはなぜだろう？」となる場合があるから。

なぜなぜ、を考え始めると全部そうじゃんってなるけど、大事なのは、
自分以外の人が理解出来ない & 出来なさそうな箇所は、自分の意図(Why)を書こう、ということ。

まとめ

サンプルコードが簡単なのであまり実感がわかないかもしれないけど、

• 他人がそのコード見て、意味だけでなく意図まで理解できるかどうか
• 理解出来ない場合、理解の手助けになるコメントを書けているかどうか

が大切。
特に大規模なシステムや、年代物のシステムだと、当時の開発担当が居ないなんて事はザラにあるので、
こういったコメントが無いと、保守する時に痛い目を見る。（実体験済み