はじめに

こんにちは、最近、コードの調査を行う機会があり、このコメント...コードと合ってなくね？的なことがありました。
そこで、コメントに関し再認識しつつ、記事でも執筆してみることにしました。
コメントについて肯定的な方と否定的な方が存在するため、記事を通じて多くの方に見ていただきたいと考えています。

記事内では、自身がよく使用するPHPを例にコードとコメントの説明を行いますが、主要な焦点はコメント自体にありますので、どのプログラミング言語の方でも多少は参考になる？？かと思います。

プログラミングにおけるコメントの役割

一般的なコメントの役割は

コメントはプログラム内に説明や注釈を追加するためのテキストです。
コード自体はコンピュータが実行するためのものであり、コメントは人間がコードを理解し、保守、協力、およびデバッグするのに役立ちます。

「コメントは人間がコードを理解」ってとこですよね...ここを上手く書いたり、時には書かなかったりするのが難しい...

以下に、コメントの主要な役割を説明します。

1. コードの説明

コードの目的や特定の処理の説明を提供するためにコメントを使用します。
これは他の開発者がコードを読む際に理解を助け、コードの意図を明確にします。

// ユーザーがログインするための関数
function login(string $userName, string $passWord) {
    // ユーザー名とパスワードを検証するコード
}

2. TODOリスト

プログラム内にTODOコメントを追加して、未解決の課題や修正が必要な箇所を記録します。
これは将来の作業の計画を立てるのに役立ちます。

// TODO: エラーハンドリングを改善する必要があります

3. ドキュメンテーション

特に大規模なプロジェクトでは、コードの全体的な構造やAPIの説明をコメントで提供し、開発者がドキュメンテーションを参照することなく理解できるようにします。

/**
 * この関数はユーザー情報をデータベースに保存します。
 *
 * @param string $userName ユーザー名
 * @param string $email メールアドレス
 */
function saveUser(string $userName, string $email) {
    // データベースにユーザー情報を保存するコード
}

4. デバッグ

デバッグのために一時的にコードを無効化するためのコメントを使用します。
これはバグを見つけたり、問題の特定箇所を調査したりする際に役立ちます。

/*
echo $variable; // 変数の内容を確認する
*/

個人的な意見ですが、3. ドキュメンテーションとかは確かにあると便利ですよね、コードの全体像が分かってから読むと頭に入ってきやすので
逆に4. デバッグとかはあまり使う機会がないですね、吐き出したくなったら自身で書いちゃうことが多いです。

コメントの使用方法

コメントはプログラム内に追加し、以下の方法で使用できます。
ここはPHPでの書き方になるので飛ばして頂いてもOKです。

1. 単一行コメント

一つの行にコメントを記述するには、//を使用します。

// この行はコメントです

2. 複数行コメント

複数行にまたがるコメントを記述するには、/*で始めて*/で終えます。

/*
  これは
  複数行のコメントです
*/

3. ドキュメンテーションコメント

PHPでは、関数やクラスの説明を記述するための特別なコメントスタイルもあります。
これらのコメントは外部ツールによって抽出され、自動的に生成されたドキュメンテーションに使用されます。

/**
 * この関数は何らかの説明です。
 *
 * @param string $param1 パラメータ1の説明
 * @param int $param2 パラメータ2の説明
 * @return mixed 関数の戻り値についての説明
 */
function exampleFunction(string $param1, int $param2): mixed
{
    // 関数の実装
}

コメントのアンチパターン

コメントを正しく使用することは非常に重要ですが、不適切な使い方も避けるべきです。
ここらへんは自身も書いてしまうことがあるので気を付けていきたいと思います。

1. 冗長なコメント

コードが自明である場合やコメント自体が役立たない場合、冗長なコメントは避けるべきです。

$counter = 0; // カウンタ変数を初期化

2. 更新されないコメント

コードが変更された場合、それに合わせてコメントも更新するべきです。
古いコメントが残っていると、誤解や混乱の原因となります。

自身が混乱した状況は、以下の通りでした。

class ReviewCollection

    /**
    * 一度に表示する数：10
    */
    public const NUMBER_TO_DISPLAY_AT_ONCE = 10;  


別ファイルで

// 一度に10レビュー表示する
$number = ReviewCollection::NUMBER_TO_DISPLAY_AT_ONCE;

その後、定数を「15」に改修の依頼があり、、、

class ReviewCollection

    /**
    * 一度に表示する数：15
    */
    public const NUMBER_TO_DISPLAY_AT_ONCE = 15;  


別ファイルで

// 一度に10レビュー表示する
$number = ReviewCollection::NUMBER_TO_DISPLAY_AT_ONCE;

このような状況に遭遇したことがあります。
別ファイルのコメントが「10」のままになっており、テストの段階まで気づくことができませんでした。
個人的には、値をコメントに含めず、呼び出し側で確認するが適切だと思います。

3. 複雑なコードの説明

コメントは補完的な情報を提供するために使用されるべきであり、コードの基本的な機能を説明するために使うべきではありません。
複難なコードを作成するのではなく、コード自体ができるだけ自己説明的であり、適切な命名や分割を行うことで、コードの可読性と保守性を向上させることが重要です。

悪い例:

// ユーザー情報を取得し、ユーザーがログインしているかどうかを確認し、ログインに関する情報をセッションに保存するコード
function complexLoginLogic($userId) {
    // 複雑な条件式とデータベースクエリ
    if ($userId && isUserLoggedIn($userId)) {
        // セッションにログイン情報を保存
        $_SESSION['user'] = $userId;
    }
}

このコメントはコードが複雑で理解しにくいことを説明しようとしていますが、コード自体が分割されておらず、コメントが過度に詳細で冗長です。

良い例:

// ログイン状態を確認し、セッションにユーザー情報を保存
function handleLogin($userId) {
    if (isValidUserId($userId) && isUserCurrentlyLoggedIn($userId)) {
        saveUserInSession($userId);
    }
}

この良い例では、関数名や変数名が自己説明的であり、コメントはコード全体の意図を説明する役割を果たしています。コードは分割され、理解しやすくなっています。

まとめ

コメントはプログラミングにおいて不可欠な要素であり、正しく使用することでコードの可読性と保守性を向上させることができます。
コメントを追加する際には、以下のポイントに注意することが重要です。

コードの意図を明確に説明するためにコメントを使用する。
コードの説明、TODOリスト、ドキュメンテーション、デバッグのために適切なコメントスタイルを使用する。
冗長なコメントや更新されないコメントを避け、コードとコメントの整合性を維持する。
複雑なコードをできるだけ単純化し、コメントは補助的な役割であることを認識する。

コメントの適切な使用により、プログラムの効果的な開発とチーム間の連携を促進していきましょう！！