kyoune01.github.io

readableCode-コメント

コメント

リーダブルコードの目的である

HTML・コードは他の人が最短時間で理解できるように書かなければならない

を達成するために、コードの「コメント」について説明していきます

自分の考えを残す

まず初めにこのような勘違いをしている人は正直に手を上げてください

優秀なコードとはコードだけで全て理解できるものである

この考え方は傲慢で間違った考え方です

下記の例では、コメントがなくても定数 MAX_COUNT に 10 が入っていることは分かります。

// MAX_COUNTに10を設定する
const MAX_COUNT = 10

適切にコメントを残すことで、そのコードを用いて
あなたが何がしたかったのか／何故そのコードを書いたのかを伝えられます

// 処理を停止するカウント上限
const MAX_COUNT = 10

繰り返しになりますが、
自分が何のためにコードを書いているのか、何故そのようなコードになったのか
説明するためにコメントを書くべきです

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

上記のコード例では、わざわざコメントすべきではない例を指摘することで、「コードを読めばわかるコメントを残す必要はない」ことを含んでいます

同様にコメントとして適切でないコメントはいくつか存在します

  • コードを読めばわかるコメント
  • 曖昧な言葉を多用したコメント
  • 失敗した命名を埋め合わせるだけのコメント

設問：上記例から 1 つ選び、コードと共にダメなコメントを答えてください。さらにダメなコメントを改善したコメントを答えてください

読み手の立場になる

上記のコメントすべきでない例を見て具体的に想像できたでしょうか？
すべき／すべきでないコメントの基準として大事な点は、コメントを残す人間が読み手の立場になっているかです

あなたが既存コードを修正する必要があったとき、下記のコメントは作業の助けになるでしょうか？

// ガードする
if($(this).find(">ul").length==0) return;

下記のようなコメントであれば嬉しいのではないでしょうか？

// 子階層がなければページ遷移させる
if($(this).find(">ul").length==0) return;

コメントはそのコードを読む他人のために残します
HTML・コードは他の人が最短時間で理解できるように書かなければならない
ために何を残すべきかを考えてみましょう

コメントは簡潔に

ここまでコメントを残す状況や考え方についてまとめてきました

まとめを読んでコメントを残す癖がついてきたあなたは、次に「沢山考えを詰め込むとコメントが長くなってしまった。仕方のないことなのかな？」といった疑問に直面することになるでしょう

// 数値の平均を計算して結果を返す関数
// 共通化できそうだったので共通化した
// でも呼んでる場所は一箇所
// ちくわ大明神
// 引数は配列であることを期待してる
const calculateAverage = function (arrayNum) {
    // body...
}

他人のために残すため、コメントはどうしても長くなる状況があります。しかしできる限り、冗長なコメントではなく簡潔で分かりやすいコメントを残せる方が「美しい」です

// 渡された配列の平均を取って返す
// 配列を引数にとり、中身はint型とする
const calculateAverage = function (arrayNum) {
    // body...
}

また、

// 速度向上のためにこの時点でデータを取得することがあるので一時的に保存する
// ↓
// キャッシュする

などのような専門用語での言い換えを用いることで、短く簡潔に残すだけでなく、認識のズレを防ぐ「美しい」コメントを残すこともできます

コメントのフォーマット

JavaScript には、大人数が関わる案件や個人間の揺れがないコメントを残すため
「JSDoc」というフォーマットが存在します

/**
 * 配列の平均を返す
 * @param  {array} arrayNum Numberを格納した配列
 *     例： [1, 3, 2, ..., (Number)]
 * @return {Number} 計算結果を返す（整数でないことがある）
 */
const calculateAverage = function (arrayNum) {
    /**
     * 配列の合計値
     * @type {Number}
     */
    let sum = 0;

    /**
     * 配列内の要素の個数
     * @type {Number}
     */
    const count = arrayNum.length;

    /**
     * 配列を一つずつ取り出し足し合わせる
     * @param  {Number} elm 配列内の数値
     */
    arrayNum.forEach(function(elm) {
        sum += elm;
    });

    return sum/count;
}

またコードに対してだけでなく、ファイルに対してコメントを残すこともあります

/********************************
 * 共通モジュール用 CSS
 *******************************/

/********************************
 *   1. base
 *   2. header
 *   3. footer
 *   4. 汎用
 *       4-1. フォント
 *       4-2. 背景色
 *       4-3. 余白
 *   5. レイアウト
 *   ...
 *******************************/

コメントとは結局「他人が処理を理解するための補助」として存在します。コメントにも規約を決め「一貫性を持って」コメントを残すことが重要です

設問：下記の関数に JSDoc のフォーマットでコメントしてください

const sumCount = function (num1=0, num2=0) {
    const sum = num1 + num2;
    return sum;
};

コメントを書く練習

ここまでコメントを残す意味やテクニックの話をしてきました。しかし中には「コメントを残すのは恥ずかしい…」「これまで書いてこなかったから書き方が分からない」といった人がいるかと思います

そんな人にコメントを残す習慣をつける、オススメの方法があります

  1. 思ったとおりにコメントをそのまま書く
  2. 一晩寝かせて深みをもたせる
  3. きれいなことばに置き換える

ことです

もし、コードを書いていて（ここの処理で文字列を渡されるとやばいな）と思うコードがあるとしましょう
まずは思ったことをそのままコメントに残していきます

// この関数に文字列を渡すとやばい

一度書き殴ってから、きれいな言葉にします
（このときにすぐ書き換えることが難しければ、一晩置くことで書き換えた言葉に深みが出ます）

// 注意：引数がint以外は処理できない
// TODO: ガード処理を入れる

結果、2 行になりましたが現状と課題が見ただけで理解できるコメントになりました

一回で良いコメントを書こうとせず、まずは思ったことをそのまま書いても大丈夫です
まずはコメントを書く習慣を身に付けることが重要です

まとめ

コメントに限った話ではないですが、技術の習得は手を動かすしかありません。他人のためのコードが残せるように沢山コメントを書きましょう

ただし最後に一つだけ注意することがあります
「ファイルに残したそのコメント、全世界に公開されてますよ？」

© 2024, kyoune01