2022.10.24

【CleanCode】より良いコードを書く技術(コメント) ③

おかざきるい

こんにちは!RuiOkazakiです!
【CleanCode】読みやすいコードを書く技術シリーズの3章目です!
前回の記事をまだ読んでいない方は前回の記事から読んでいただけると更に理解が深まると思います!

  1. 導入編
  2. 命名規則編
  3. コメント( ← 現在のページ )


なぜコメントが必要なのか

コードで意図が全て伝えることができるのならコメントは要りません。
さらに言うと、「情報も持たないコメント」「誤情報を含むコメント」は邪魔にしかならないため「価値のあるコメント」を心がけましょう。

コメントが必要なケース

  • コードでうまく表現できない場合に、それを補うとき
  • 意味や意図、考えを伝えるとき
  • 覚え書きや注意を促すとき(NOTEやTODOなど)

コメントのデメリット

  • コメントはコードではないため、書いてあることが正しいとは限らないこと
  • メンテナンスがめんどくさいこと(メンテナンスをしないコメントは書かない方が良い)
  • 幅を取るため無駄なコメントは見通しが悪くなるだけ


コードで意図を表す

コメントを残すのではなく、関数名をわかりやすくすることでコメントを読まなくてもどう言う処理が行われるかがわかるようになる。

// 未成年ならtrueを返す
const getBoolean = (num) => {
  return num < 18;
}
const isNotAdult = (age) => {
  return age < 18;
}


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

コメントを読むのにも時間がかかるため、コードから読み取れる情報を書いてしまうと冗長になってしまいます。

// ユーザーの性別が男性の場合処理を行う
const GENDER = {
  male: 'male',
  female: 'female',
  nonbinary: 'nonbinary'`
}
if(user.gender === GENDER.male) {}

ユーザーの性別と性別を格納しているenumを比較しているのが直感的に理解することが出来る。

良いコメントとは?

  • TODOコメント
  • 使用上の注意 / 警告
  • 公開するライブラリのための API コメント
  • コピーライトコメント
  • パフォーマンスなどに関わるコメント
  • 複雑な処理が避けられない場合に補足説明するコメント(正規表現のコメントなど)


良いコメントの例

// TODO: Promise.all に置き換えることができるかも
for (let i = 0; i <= 3; i++) {
  new Promise((resolve, reject) => {
    resolve(result);
  });
}

TODOコメントは実装漏れを防いだり、意図を書き残す有効的な手段なので実装中に懸念点なのがある場合は積極的に使用していきましょう!

/**
 * @param {"ja" | "en" | "fr" } lang
 * @returns {string}
 */
function getGreeting(lang) {
  return greetings[lang];
}

こちらはJSDocというコメントの残し方です。
関数や変数の宣言の直前に/* ◯◯ /を書く記法のことで、関数や変数の使い方などをエディター単位でサポートしてくれるようになります!
上記のコメントを残した場合は下記のように表示されます。
Google JavaScript スタイルガイドでも採用されている記述方法でドキュメントを自動生成することなどもできるのでOSSなどを開発する際やチームで開発する際は使用を検討してはいかがでしょうか!

悪いコメントとは?

  • 意味のないコメント
  • 冗長なコメント
  • 形式的なコメント
  • コメントアウトされたコード
  • 位置取りのための強調コメント
  • 改修履歴コメント
  • バージョン管理のためのコメント


悪いコメントの例

// 20代男性、技術職、年収200万円以上、大阪府なら true
if (
  20 <= age &&
  age <= 29 &&
  occupation === 1 &&
  200 <= salary &&
  prefecture === "osaka"
) {
  return true;
}
return false;

一見わかり辛いif文の中身をコメントで書き残していて良いコードだと考えられがちですが将来条件を変更する際にどの比較演算子が何の値を指しているかがわかりません。
また、コメントが最新とは限らずメンテナンスされていない可能性があるので変数名にすることで条件を変更する際などにも分かりやすくなります。

const isTwenties = 20 <= age && age <= 29;
const isTechnicalJob = occupation === 1;
const isSecondsMillionYenOrMore = (salary) => 200 <= salary;
const livingInOsaka = prefecture === "osaka";

const isTarget = ({ salary }) => isThirties && isTechnicalJob && isSecondsMillionYenOrMore(salary) && livingInTokyo;

if (isTarget({ salary })) {
  return true;
}
return false;

変数に格納することで条件式が何を現しているかがすぐわかりif文がごちゃごちゃせずにシンプルに書くことができます。
コメントは嘘を付く場合がありますがコードは嘘をつかないので複雑な条件式を扱う場合は積極的に使用しましょう!!

まとめ

ご清覧ありがとうございました!
変数の定義へ

  • 初心者
  • JavaScript

おかざきるい

フロントエンド中心にコード書きます。邦ロックとアイスとカメラが好きです。

トップページへ戻る

こちらの記事もおすすめ

【色彩検定の勉強に】色はなぜ見えるのか?のサムネイル

2022.06.02

【色彩検定の勉強に】色はなぜ見えるのか?

こばやしたいよう

【CleanCode】より良いコードを書く技術 ①のサムネイル

2022.10.05

【CleanCode】より良いコードを書く技術 ①

おかざきるい

初心者がフロントエンドエンジニアとして全国2位になれた勉強法のサムネイル

2022.06.15

初心者がフロントエンドエンジニアとして全国2位になれた勉強法

おかざきるい