変数、関数、クラスのためにより良い名前を付ける方法 – 例を交えて

命名は、クリーンでメンテナブル、スケーラブルなコードを書く上で最も重要で挑戦的な部分の一つです。例えば、よく考えられた変数名は自己文書化されたコードとして機能し、ロジックを理解するための時間と労力を節約します。しかし、選択が不適切な名前は、混乱やバグを引き起こす可能性があります。

この記事では、クラス名、変数、関数に意味のある名前を考案するための包括的なガイドを、例とベストプラクティスを交えて提供します。

なぜ命名が重要なのか？

• 可読性： 良い名前はコードを直感的にし、他の人の学習曲線を減らします。

• メンテナンス性： よく名付けられたコードはリファクタリングやデバッグが容易です。

• 協力： 明確な名前はチームのコミュニケーションと生産性を向上させます。

• スケーラビリティ： 意味のある名前は大規模プロジェクトを管理しやすくします。

異なる命名規約スタイル

異なる命名規約スタイルは、さまざまなプログラミング言語におけるコードの可読性とメンテナンス性を向上させる上で重要です。

camelCase、PascalCase、snake_case、およびkebab-caseなどのスタイルは、特定の文脈や実践に合わせて調整されています。

camelCaseは変数や関数で広く使用されており、一方、PascalCaseはクラスで好まれています。 snake_caseはPythonで人気があり、kebab-caseはHTML要素のスタイリングでCSSを支配しています。

各スタイルは一貫性を確保し、チームや将来の開発者にとって直感的なコードを作成します。以下は、いくつかの人気のある命名規則の簡単な要約表です。それぞれの使用例と例も示しています。

正しいスタイルの選び方

1. 言語固有: プログラミング言語またはフレームワークの慣習に従ってください。例えば：

   • JavaScript: camelCaseは変数と関数に、PascalCaseはコンポーネントに使用します。

   • Python: snake_caseは変数と関数に使用します。

   • CSS/HTML: kebab-caseはクラス名とIDに使用します。

2. チームまたはプロジェクトの標準: 一貫性が重要です。チーム/プロジェクトで合意されたスタイルを使用してください。

3. 特定の目的に合わせた: 名前付けスタイルは、名前付けされるエンティティを最もよく表すものを使用してください（たとえば、定数はSCREAMING_SNAKE_CASEで表されます）。

一般的な命名ガイドライン

クラス名、変数、および関数のための具体的な命名規則に取り掛かる前に、いくつかの普遍的な原則を探ってみましょう:

1. 記述的で簡潔であること: 名前は変数/関数などの目的や役割を伝えるべきです:

    // 悪い例
    let x = 10;
   
    // 良い例
    let maxUsersAllowed = 10;
   

2. 他の開発者が理解するのが難しいかもしれない暗号化された省略形を避けてください（将来の自分でも）：

    // 悪い例
    let usrNm = "John";
   
    // 良い例
    let userName = "John";
   

3. 一貫した命名規則を使用してください：プロジェクト全体でcamelCase、PascalCase、kebab-case、snake_caseなどの命名スタイルを選択し、それに従ってください。

4. 予約語や混乱を招く名前を避ける：

    // 悪い例
    let let = 5;
   
    // 良い例
    let variableName = 5;
   

さて、基本をカバーしたところで、いくつかの有益な命名規則について詳しく見ていきましょう。

良いクラス名の作成方法

クラス名は、アプリケーション内の要素の視覚的または構造上の振る舞いを定義します。わかりやすいクラス名を付けることで、HTMLとCSSが理解しやすく保守しやすくなります。

1. 記述的な名前を使用する

クラス名は、要素の目的を説明するべきであり、外観ではないべきです。

<!-- 悪い例 -->
<div class="red-button"></div>

<!-- 良い例 -->
<div class="primary-button"></div>

2. BEM（Block-Element-Modifier）メソドロジーに従う

BEMは、スケーラブルで保守しやすいCSSを記述するための人気のある規約です。コンポーネントを以下のように分割します：

• ブロック:コンポーネントを表します（例：card）。

• 要素:ブロックの子要素を表します（例：card__title）。

• 修飾子:ブロックや要素のバリエーションを表します（例：card__title--highlighted）。

例:

<div class="card">
  <h1 class="card__title card__title--highlighted">Welcome</h1>
  <p class="card__description">This is a card component.</p>
</div>

3. kebab-caseを使用する

CSSクラス名は伝統的にkebab-caseで記述され、可読性が向上します。

<!-- 悪い例 -->
<div class="primaryButton"></div>

<!-- 良い例 -->
<div class="primary-button"></div>

良い変数名の作成方法

変数はデータを保持し、それが何を表しているかを説明する意味のある名前を持つべきです。

1. 変数には名詞を使用する

変数は通常、名詞であり、エンティティやデータを表しているためです。

// 悪い例
let a = "John";

// 良い例
let userName = "John";

2. コンテキストを追加するためにプレフィックスを使用する

プレフィックスを追加すると、変数のタイプや目的が明確になります：

• ブール: is, has, can

• 数字: max, min, total

• 配列: 複数形を使用します（例：users, items）。

例:

let isUserLoggedIn = true;
const maxUploadLimit = 5; // MB
const usersList = ["John", "Jane"];

3. 一般的な名前を避ける

data, value, や item のような名前は、必要な場合を除いて避けます。

// 悪い例
let data = 42;

// 良い例
let userAge = 42;

良い関数名の作成方法

関数はアクションを実行するので、その名前は実行する操作やプロセスを反映すべきです。

1. 関数には動詞を使用する

関数はアクション指向なので、その名前は動詞で始めるべきです：

// 悪い例
function userData() {
  // ...
}

// 良い例
function fetchUserData() {
  // ...
}

2. 機能について具体的に説明する

関数名は、その機能を示すべきです。

// 悪い
function handle() {
  // ...
}

// 良い
function handleFormSubmit() {
  // ...
}

3. 意図のためのプレフィックスを使用する

• イベントハンドラの場合: handle, on

• ユーティリティの場合: calculate, convert, format

• フェッチ操作の場合: fetch, get, load

• セッターとゲッターの場合: set, get

例:

function handleButtonClick() {
  console.log("Button clicked!");
}

function calculateDiscount(price, discountPercentage) {
  return price * (discountPercentage / 100);
}

変数、関数、またはクラスに適した名前かどうかを知る方法

名前が変数、関数、またはクラスに適しているかを理解するためには、いくつかの重要な原則を評価することが重要です。ここでは、プログラミングの文脈で名前が適切で意味のあるものであるかどうかを判断するためのガイドを示します:

1. 目的を表していますか？

目的に基づいた名前は良い名前の最も重要な特徴です。名前は追加のコメントやドキュメントを読む必要なく、変数、関数、またはクラスが何を表しているか、または何をするかをすぐに伝えるべきです。

評価方法:

自問してみてください:「この名前を読んだとき、その目的がすぐに理解できますか？」

例:

• userAgeはaよりも優れています。なぜならuserAgeは変数が何を表しているかを示しているのに対し、aはあいまいすぎるからです。

2. 十分に具体的ですか？

名前はコード内のエンティティの正確な役割を反映するには十分に具体的である必要があります。dataやtempのような過剰に一般的な名前は十分な文脈を提供しないため、混乱のもとになります。

評価方法:

尋ねてみてください:「この名前は、この変数、関数、またはクラスが私のアプリケーション内で表しているものに特化していますか？」

例:

• calculateTaxAmount()はcalculate()よりも優れています。なぜなら関数が何を計算しているかが明確だからです。

3. 一貫した命名規則に従っていますか？

命名規則の一貫性は非常に重要です。すべてのチームメンバーが同じ規則に従うと、コードを理解しやすく移動することができます。

評価方法:

この名前は、プロジェクト全体で使用されている命名規則と一致していますか？プロジェクトガイドラインに従ってください:

• 変数や関数にはキャメルケースを使用します（例：userAge）

• クラス名にはパスカルケースを使用します（例：UserProfile）

• 定数には大文字スネークケースを使用します（例：MAX_USERS）

例:

• チームがキャメルケースを使用している場合、userDataはUserDataよりも適しています。

4. 曖昧さを避けていますか？

良い名前は曖昧さを排除します。複数の解釈が可能であってはいけません。異なる文脈で異なる意味を持つ場合、混乱を招きます。

評価方法:

尋ねてみてください: “コードベースに馴染みのない人でも、この名前が何を指しているのかを誤解する可能性がありますか？”

例:

• ブール値をisValidと命名する代わりに、isUserLoggedInやisEmailVerifiedを使用して、何がチェックされているのかをより明確にします。

5. 読みやすく発音しやすいですか？

厳密に必要ではありませんが、読みやすさと発音のしやすさは、コード全体の可読性と保守性を向上させることができます。

評価方法:

質問してください：”この名前は声に出しやすいですか？一目で理解できますか？”

長い名前は避け、一般的な略語は広く受け入れられている場合にのみ使用してください。

例:

• maxRetriesはmaximumNumberOfAttemptsToReconnectよりも良いです。

6. 冗長性を避けていますか？

名前には冗長性を避けてください。すでに暗黙的またはコンテキストで説明されている情報を繰り返さないでください。

評価方法:

質問してください：”周囲のコンテキストから明らかな情報を繰り返していますか？”

例:

• クラス名がUserの場合、メソッド名をuserGetData()とするのは冗長です。代わりにgetData()を使用してください。

7. 自己記述的ですか？

最適な名前は自己説明的です。良い名前は追加のコメントや説明を必要としません。

評価方法:

質問してください：”この名前は変数や関数、クラスを完全に説明していますか？何をするかを説明するためのコメントが必要ですか？”

例:

• calculateTotalPriceは自己説明的ですので、「この関数は割引後の合計金額を計算します」といった追加のコメントは必要ありません。

8. コンテキストに即しており、ドメインに関連していますか？

名前はプロジェクトやそのドメインのコンテキストに適合している必要があります。たとえば、Webアプリケーションの命名規則は、モバイルアプリや機械学習モデルのそれとは異なるかもしれません。

評価方法：

「この名前は私のプロジェクトのドメインとコンテキストに適合していますか？」と問いかけます。

特定のドメイン（たとえば、ファイナンス、健康、ゲームなど）で作業している場合は、認識しやすいドメイン固有の用語を使用してください。

例：

• ゲームアプリでは、healthPointsはhpよりも適切であり、その意味を反映しています。

9. 将来に耐えられるか？

コードがどのように進化するかを考えてください。名前は将来の変更に柔軟に対応できるようにする必要があります。

評価方法：

「機能が変わったり、プロジェクトが成長した場合でも、この名前は依然として意味をなすでしょうか？」と問いかけます。

例：

• userInfoはデータ構造が変わると古くなる可能性があります。より多くのフィールドが追加されることを予想する場合は、userProfileを使用する方が良いでしょう。

10. マジックナンバーやハードコーデッドされた値を避けていますか？

マジックナンバー（意味が不明な数値）は、名前付き定数の使用を優先して避けるべきです。

評価方法:

問いかけ: “この名前は意味のある定数を表していますか、それとも単なる生の数値ですか？”

例:

• 1000を使用する代わりに、MAX_FILE_SIZEのような定数を使用して、その数値の背後にある意味を説明します。

実用例

CSSの例

以下のCSSの例は、スタイルシート内で構造化されたスケーラブルなクラス階層を維持するために、BEM（ブロック-エレメント-モディファイア）命名規則を適用する方法を示しています：

<!-- HTML -->
<div class="navbar">
  <ul class="navbar__list">
    <li class="navbar__item navbar__item--active">Home</li>
    <li class="navbar__item">About</li>
    <li class="navbar__item">Contact</li>
  </ul>
</div>

/* CSS */
.navbar {
  background-color: #333;
  padding: 10px;
}

.navbar__list {
  list-style: none;
}

.navbar__item {
  display: inline-block;
  padding: 10px;
}

.navbar__item--active {
  color: orange;
}

このコードで何が起こっているかは次の通りです：

• BEM命名: navbarはブロックであり、主なナビゲーションコンポーネントを表します。

• navbar__listはエレメントであり、ブロックの子要素で、ナビゲーションアイテムのリストを表します。

• navbar__itemは、個々のリストアイテムを表す別のエレメントです。

• navbar__item--activeは、アクティブなメニューアイテムを強調表示するための修飾子で、HTMLとCSS内の関係と役割を理解しやすくし、モジュール化および再利用可能なスタイルをサポートします。

JavaScriptの例

このJavaScriptの例では、変数と関数の意味のある一貫した命名規則を使用して、コードを自己説明的にする方法を示しています。

// 変数
let isUserLoggedIn = false;
const maxAllowedItems = 10;

// 関数
function fetchUserDetails(userId) {
  // APIからユーザーデータを取得する
}

function calculateTotalPrice(cartItems) {
  return cartItems.reduce((total, item) => total + item.price, 0);
}

コード内で何が起こっているかを次に示します：

• 変数：

  • isUserLoggedIn：その目的を明確に示すために命名されたブール変数。 isを接頭辞として付けると、それがブールであることがわかります。

  • maxAllowedItems：大文字のmax接頭辞が付いた定数は、制限であることを示し、意図が明確になります。

• 関数:

  • fetchUserDetails(userId): 関数の目的を反映した名前で、ユーザーの詳細を取得することがその目的です。 パラメータ userId は説明的で曖昧さを避けています。

  • calculateTotalPrice(cartItems): 関数名は明示的に実行されるアクションを述べています。 cartItems パラメータは、電子商取引ドメインに関連しています。

良い点: これらの規約により、コードが読みやすく直感的になり、同じプロジェクトで作業する他の開発者の認知負荷が軽減されます。

結論

意味のある名前付けは、コードの読みやすさと保守性に大きく影響する重要な規約であり、芸術でもあります。

これらの基本原則に従うようにしてください:

• 記述的で簡潔な名前を使用します。

• クラス名には BEM、変数と関数には camelCase のような一貫した規約に従います。

• 文脈と明瞭さを追加するために接頭辞を使用します。

ここで議論したこれらのヒントとその他のヒントに従うことで、数ヶ月後にコードを再訪したりチームと協力したりする際にも、コードを使うことが楽しくなります。 今日からこれらのヒントを適用し、コードの品質が向上するのを見てください。