kyoune01.github.io

readableCode-命名

命名

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

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

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

明確な名前を選ぶ

まず変数を命名するときに皆さんは何を基準に命名するでしょうか？
一番多いパターンは機能で命名することでしょうか？

getParam(t)
.alignRight

ここで質問です
上記から要素の横幅を取得する関数とテキストを右寄せするクラス名だと判断できましたか？

エスパーでない人のために、名前に対してさらにヒントを増やします

getElementWidth(target)
.text-alignRight

これなら名前をみただけで役割を察することのできる情報量になりました

命名をするときに大事なことは、役割を一目で明確に把握できること、です
短く不明瞭な命名より、冗長でも明確な命名を意識してください

命名するときは日本語ではなく英単語で命名します
また名前の中で一番重要な単語を先頭に置きます

変数：体言止め
「天気の情報 = weatherData」
「要素の横幅 = width(Element)」

関数：動詞を先頭におく
「天気の情報を取得する = fetchWeather()」
「CSV 用に受け取った値を整形する = formatForCSV()」

設問：適切な命名をしてください

  1. クリックされたときにナビゲーションを表示する関数
  2. コンテンツを非表示にする関数
  3. 要素から飛び出る長さのテキストを空白で改行する汎用クラス

省略しない

業務でクラス名・関数を命名する必要がありました

カレンダー要素のインナークラス
要素を角丸にするクラス
天気の情報を取得する関数

しかしタイプを面倒くさがったあなたは下記のように省略をした命名をしました
名前だけで役割を判断できる命名ができているでしょうか

.clI { ... }
.bd-r { ... }

const getTmpVal = function (a) {
    // body...
    return r;
}

「他人も理解できるだろう」といった傲慢な姿勢で命名し、数秒を面倒くさがった結果、自分は理解できてても他人にはまったく意味の分からない名前になりました

他人が理解できない命名は、今後保守をする全ての人の時間と脳のリソースを占領する負債です
基本的に、命名を省略してはいけません
※判例として省略されている名前など一部の例外は存在します

抽象的な名前より具体的な名前を使う

ここまでの資料を読むと当然、（自分の命名は他人から分かりやすい命名ができているだろうか？）のような疑問がわきます
自分の命名に不安を感じたとき、命名に慣れるまでの間は下記を意識してみてください

  • 実装を始める前に、代わりとなる単語がないか他の候補を探す
  • get, value, param など、汎用的な名前だけの命名を避ける
  • 動作、対象、単位など、これでもかと情報を詰め込む
  • 定数、グローバル変数、イレテーターなど、扱いの違いでフォーマットを統一する

設問：下記の関数名や引数、返り値を適切な命名へ修正しなさい

/**
 * 天気の情報を取得する関数
 * @param  {strign} 情報を取得したいエリアID
 * @return {array}  取得結果
 */
const getTmpVal = function (a) {
    // body...
    return r;
}

一対一対応な命名

最後に「命名」と「美しさ」の複合として、一対一対応な名前を説明します

対象を表示する関数と非表示にする関数を実装しました

hiddenTarget() / enableTarget()

ところで「美しさ」の資料では「一貫性と意味のある並び」について説明しました。上記を考慮すると関数名も「on/off の一対一対応している」命名が美しくなります
「美しさ」の資料に則って命名すると下記のようになります

hiddenTarget() / showTarget()
disableTarget() / enableTarget()

役割が対応する機能を実装するときは、名前も対応しているか意識してください。また相反だけでなく、「first / last」など終始がわかる命名も「美しい」命名です

設問：下記の命名に対応する名前(対義語)を考えてください

  • rangefirst
  • beginEvent()
  • .btn-show

まとめ

命名は読みやすさに大きく影響する要素です
負債を生まない・増やさないよう、下記を意識して大事に命名してください

  • 役割を他の人が理解できる情報量か
  • 異なる解釈をされない単語を選べているか
  • 一貫性を持って書かれているか
  • 対応する命名ができているか

日本語から命名を考えてくれるサービス（codic）も存在します
命名について悩んだときは周りの人に相談してみましょう

© 2024, kyoune01