コメントについて意識すること🖊️

コメントを書く上で意識することは

できるだけコードで表現して、表現できない場合だけコメントに残す

ことだと考えています。

なぜならコメントを書いたところで実際の処理に影響しないからです。
実際のプログラムはコメントではなくコードが全てだからです。

さて、ここから具体的に悪いコメント・良いコメントを見ていきましょう！

悪いコメント😣

さっそく悪い・不要なコメントを見ていきましょう！

当たり前のことは書かない

ついついやってしまいがちなので、
頭に叩き込んでおきたいこと、

当たり前のことはコメントしないです。

以下の4つ例は

パッとみれば分かる
意味がないコメント

なのでコードリーディングの妨げになってしまいます・・・

// 10回ループさせる--(1)
for (var $i = 0; $i < 10; $i++) {
  echo $i
}

// 20歳以上の場合--(1)
if(age > 20){
  ...
}

// ステータスアップデート--(2)
function statusUpdate($user) {
}


// ユーザークラス--(2)
class Users(){
}

条件分岐の解説

続いて、これもよくやりがちなケースです。
条件分岐について、こまごまとコメントしてしまう・・・
以下の条件分岐２つもパッと見て理解できる条件ではないでしょうか。

// 未成年かつメンバー会員の場合
if ($user->age < 18 && $user->is_member){

// 未成年以上かつメンバー会員の場合
} elseif ($user->age >= 18 && $user->is_member){

}

また上記の場合は、条件式を関数にして、
分かりやすい関数名をつけることで、
よりコードリーディングがスムーズになります。
true または false を返すboolean型の関数であれば
is has can を関数名の頭に付けることで直感的に理解できます。

if (isMinorMember($user)){

}else{

}

// 未成年かつメンバー会員であるかを判定する
function isMinorMember($user) {
    return $user->age < 18 && $user->is_member;
}

良いコメント😄👌

さて、コメントするべきコードとは？

コードでは表現できない、意図が伝わらないコード

にコメントをすべきだと考えています。

コードだけでは表現しきれない
パッと見て意図が分からない
他のメンバーが後々なぜこのような処理をおこなっているのか確認しなければならない

このような場合にコメントをしたいものです。

// 以下カラムは入力フォームが存在しないが、セットしないと保存時エラーとなる。--(1)
if ($userEntity->isNew()){

  // TODO:料金カテゴリ設定機能は未実装のため仮でその他を指定する。--(2)
  $userEntity->price_category = OTHER_PRICE;

  // 新規の場合は必ず一般ユーザーで登録する --(3)
  $userEntity->type = NORMAL_USER;
}

$userEntity->isNew()の条件だけでは、なぜこのような処理を行うのか分からないためコメントを追加。
TODO:として開発中のメモを記録します。TODOとすることで後々処理が必要と目印にもなります。
コメントなしだと仕様上の処理であることが理解できません。

ドキュメントコメント

ドキュメントコメントはコードに対して説明や注釈を付けるための特別な形式のコメントです。

関数やメソッドの役割、引数、戻り値などを明確にすることで、コードの理解が容易になります。
型チェックが行われる。
IDE(VSCode)補完されため早期エラーを確認できる。

このような目的で使用されます。
また各言語に特化したドキュメントコメントがあり、参考にPHPのドキュメントコメントを見てみましょう！

PHPDoc

以下はPHPDocの具体例です。

/**
 * 関数やクラスの内容を説明します。
 * 
 * @param 型・ネームスペース 対象の変数等 説明
 * @return 型 説明
 * @throws 型 説明
 */

実際のユースケースを確認してみましょう。
定義した関数のパラメータや戻り値について具体的に説明を記載します。

/**
 * ユーザー編集画面から送信されてくるパラメーターを基にユーザー情報を編集する
 * 
 * @param \App\Model\Entity\User $entUser 変更するエンティティ
 * @param array $params 編集パラメーター
 * @throws \Exception 保存に失敗した場合
 * @return \App\Model\Entity\User
 */
public function editUser($entUser, $params){
    try {
        if ($tblUsers->save($entUser)) { 
            throw new \Exception('保存に失敗しました');
        }
        return $entUser;
    } catch (\Exception $e) {
        throw $e; // 例外を再スロー
    }
}

まとめ🖊️

ご覧いただきありがとうございました！
コメントについては未だに書くべきものと書かないほうがいいものが混乱しますが、
リーダブルコードやクリーンコードを読み返して復習してモノにしていきたいです！

何か気になる点や、おかしな点ありましたらお気軽にコメントください！