“このdayって何の日？”──読む人を悩ませない命名のコツ

はじめに

• dayって何の日付？
• statusは何のステータス？
• userってどのユーザー？

以前、私が仕事で扱ったシステムのコードでは、dayやstatus、userのように、
あまりにも汎用的な意味の変数名ばかり使われていて、処理内容を読み解くのが本当に大変でした。

そこで、「どうすれば他人にも自分にもわかりやすい名前をつけられるのか？」 が気になり、
命名の基本原則やベストプラクティスを調べてみました。

言語に依存しない内容ですが、Pythonを中心に例を挙げています。

一貫したルールに従う

どんな命名ルールを使ってもOKですが、プロジェクト内で統一することが重要です。
採用すべきルールの例としては以下のようなものがあります。

ケーススタイル

どれを使ってもOK、どれか1つに統一する。

ケース名	例	主な用途
スネークケース	user_name	Python変数、関数
キャメルケース	userName	JavaScript変数
パスカルケース	UserProfile	クラス名

動詞と名詞の使い分け

名前を付けるものの種類によって使用する品詞を分ける。

種類	命名の形	例
関数・メソッド	動詞＋目的語	send_email, calculate_total
変数・クラス	名詞	user, payment_service

接頭辞・接尾辞

似たような処理には共通パターンを持たせる。

種類	命名パターン	例
取得系	get_	get_user, get_order
変換系	to_	to_json, to_dict
テスト関数	test_	test_user_login

命名ルールはチームで共有・自動化

• 命名規則をドキュメント化して共有する。
• リンター（flake8, pylint, ESLintなど）を導入して自動チェックする。

✅ チーム全体で統一感を保ち、レビューの負担を減らせます。

短すぎる名前はNG

1単語の名前は避ける

email  # ❌ 何を表す？アドレス？メッセージ？
email_address  # ✅ より明確
email_message  # ✅ より明確

汎用的な単語の使用は特に注意

• data, result, status のような汎用的な単語は意図がぼやける。
• 一時変数によく使われる tmp, temp も使用は避ける。

pending_user  # ✅ 登録待ちのユーザー
temp_user     # ❌ 何が「一時的」なのか不明

1〜2文字の名前も避ける

a, b, c などの短い名前は、ループ変数など明確な用途がある場合のみ使用します。

for i in range(10):  # ✅ OK（ループ変数として慣例的に使用）
    ...

他にもX軸の値を表す変数を x, Y軸の値を表す変数を y とするような場合は1文字でもOKです。

略語を使わない

略語を使うと、エディタ検索やGitHub検索でヒットしにくくなります。

copy_data  # ✅
cpy_data   # ❌

一般的に認識されている略語（HTML, URL, DB など）の使用はOKです。

不要な情報は省く

クラス名を属性に含めない

「何を表すか」が伝わる範囲で簡潔に。

class Cat:
    def __init__(self, weight):
        self.weight = weight  # ✅ catweight とは書かない

名前に数字を含めない

payment1 = ...
payment2 = ...
payment3 = ...

このように数字で名前を分けると違いがわかりにくいので、
それぞれ別の名前にするか配列や辞書で管理する方が良いです。

名前にデータ型を含めない

データ型がなくても困らないことが多いです。

name      # ✅
name_str  # ❌

より伝わりやすくするための工夫

真偽値変数、関数には is / has をつける

「真偽の状態が何を表す変数か」や「何を返す関数か」が名前から一目でわかるようになります。

is_valid_email = True

def has_permission(user: User) -> bool:
    ...

否定形を避ける

if not is_valid:  # ✅ 読みやすい
if is_not_valid:  # ❌ 二重否定になりがち

単位を名前に含める

単位を含めることで、意味がより明確になります。

weight_kg = 5.2
length_m = 3.0

集合体は複数形にする

user = "Alice"     # ✅ 単体
users = ["Alice", "Bob"]  # ✅ 集合

注意点

ビルトイン名を上書きしない

list, id, sum, type など、組み込み関数名は避ける。

list = [1, 2, 3]  # ❌
my_list = [1, 2, 3]  # ✅

将来的な変更を考慮した命名を

• 技術やフォーマットを名前に埋め込まない
  read_csv() → 将来JSON対応するなら load_data() の方が柔軟。
• 型名を含めない
  user_list → 将来setやdictに変わる可能性あり。

おわりに

改めて調べてみると思ったよりも考慮すべきことがたくさんあることがわかりました。
自分で付けた名前でも時間が経ってから見ると意味がわからなくなることが多々あるので、
これらのことを意識して自分も他人もわかりやすい命名を心掛けようと思います。