🦁

何をコメントすればいいのか

2023/08/09に公開

コメントすべきではないこと

【コードからすぐに推測できるようなこと】

// ユーザー情報を更新
updateProfile(user.info)

// ユーザー情報を取得する
getProfile(user.id)

上記のように変数から容易に推測できるコメントは不要

【コメントのためのコメントをしない】

// 以下コメントアウト
// ユーザー情報を更新
setProfile(user.info)

コメントすべきこと

【自分の考えを記録する】

// このクラスは汚くなってきている
  // サブクラスを作成し、整理した方が良い
  class xxx {
   // 処理
  }

このコードのおかげでチーム開発時、ほかのメンバーにも共有ができる。

【コードに改善が必要な場合はTODOを残しておく】

 {
    // TODO: もっと早いアルゴリズムを使う
  }

TODO関連のコメント記法を下記にまとめておく

記法	典型的な意味合い
TODO	あとで手をつける
FIXME	既知の不具合があるコード
HACK	あまり綺麗じゃない解決策
XXX	危険!大きな問題がある

【要約コメントを残す】

 for(let i=0; i<users.length; i++){
   // 管理者ユーザー情報を取得し整形した上で配列へ格納
   if(users[i].admin){
     // 長い処理
   }else{
    // 長い処理
   }
 }

後に続く処理が長いor複雑な場合は処理の要約を付与しておくのが好ましい。

【ブロック単位で要約コメントを残す】

 const GenerateUserReport = () => {
   // ユーザーのロックを獲得する
   {
    // 処理 
   }
   // ユーザー情報をDBから読み込む
   {
    // 処理 
   }
   // 情報をファイルへ書き出し
   {
    // 処理 
   }
   // このユーザーのロックを解放する
 }

関数の中で複数の処理が走っている場合はブロック単位でコメントを書いておくと見やすくなる。

参考にさせて頂きました。

コメントすべきではないこと

コメントすべきこと

Discussion