意味のある変数名・関数名を使う

「変数名、つい x や data にしてしまう…」そんな経験はありませんか？

Pythonの命名規則は、初心者のうちから身につけると、その後の学習と実務がぐっと楽になります。名前はただのラベルではなく、コードの意味を伝える“文章”の一部です。読み手（未来の自分も含みます！）にやさしい名前を付けることで、バグの発見も修正もスムーズになり、チーム開発でも信頼される書き方になります。

ここでは、Pythonの命名の基本を、IT初心者にもわかりやすく解説します。

「どんな名前なら読みやすい？」「よくあるNGは？」といった疑問にも答えながら、実践的なコツを身につけましょう。

意味のある変数名

まずは変数名から。

変数名は、その変数が何を表すのかをはっきり伝えるのが基本です。後から見返しても一瞬で理解できるか、を基準に考えてみましょう。

例えば、次のような名前は避けたい例です。パッと見て役割がわかりませんよね。

x = 10  # 何を表しているのか不明

一方で、次のように具体的な意味を持つ名前にすると、読み手は迷いません。

age = 10  # 年齢を表す変数

では、実際のコードの中で「意味のある名前」がどのように効いてくるのか、サンプルで確認してみましょう。

サンプルコード（変数名の例）

以下は、学生の成績の平均を計算して表示するシンプルなプログラムです。変数名に「役割」が伝わる名前を使っています。

def calculate_average_grade(grades):
    total = sum(grades)
    number_of_grades = len(grades)
    average = total / number_of_grades
    return average

student_grades = [85, 90, 78, 92, 88]
average_grade = calculate_average_grade(student_grades)

print(f"平均成績: {average_grade:.2f}")

このコードでは、まず calculate_average_grade という関数名が「平均成績を計算する」という意図を明確にしています。引数の grades は「成績のリスト」であることが名前から分かります。関数の中でも、合計は total、要素数は number_of_grades、平均は average と、その都度「何を表しているのか」を名前で説明しています。関数の外でも、student_grades が「学生の成績一覧」、average_grade が「計算された平均値」であることが読み取れます。変数名だけでコードが“自己説明的（self-documenting）”になっているのがポイントです。

変数名をつけるときのポイント

変数名を付けるときに迷う場合のために、よく効くチェックポイントを用意しました。読みやすさを上げるちょっとした工夫が詰まっています。

• 使う前に一言で説明できる名前か確認する（例: “これは年齢のリスト”→ ages）
• snake_case（小文字＋アンダースコア）で書く（例: total_price, user_count）
• 複数の値を入れるコレクションは複数形にする（例: grade -> grades, user -> users）
• 単位が重要なら名前に含める（例: timeout_seconds, size_mb）
• 真偽値は is_/has_/can_ で始める（例: is_valid, has_error, can_retry）
• 予約語は避ける（例: list, dict, id などはそのままでは使わない）
• 一文字名は原則NG。ただし i, j は短いループや数学的処理に限ってOK
• 曖昧な単語は避ける（data, info, value はできれば具体化する）

意味のある関数名

次は関数名です。

関数は何をするのかを動詞から始めて表現すると、ぐっと読みやすくなります。名前だけで用途が伝われば、実装を開かなくてもコード全体の流れを追いやすくなります。

例えば、次の関数名では意図が分かりません。何をするの？という疑問が残りますよね。

def func(x):
    return x * 2

意図が伝わる名前にすると、読み手の認知負荷が下がり、バグも見つけやすくなります。

サンプルコード（関数名の例）

以下は、与えられた数の平方を計算する関数です。名前だけで何をする関数かが明確です。

def calculate_square(number):
    return number * number

number_to_square = 5
square_result = calculate_square(number_to_square)

print(f"{number_to_square}の平方数は: {square_result}")

関数名の calculate_square は「平方を計算する」という動作をそのまま表しています。引数名の number は受け取る値の意味を簡潔に説明し、戻り値を受け取る変数 square_result も「計算結果」であることを伝えています。number_to_square という変数名は「どの数を平方にするのか」が明確で、コードを上から下へ自然に読み進められるようになっています。

関数名をつけるときのポイント

関数名で迷ったときのコツを、使う前の“ひとこと”チェックとしてまとめておきます。実装に入る前に名前を整えるだけでも、コードの品質が上がります。

• 動詞から始める（calculate_total, fetch_user, convert_to_json）
• 状態を判定する関数は is_/has_/should_ で始め、真偽値を返す
• 副作用がある関数は名前で分かるように（send_email, save_record）
• あいまいな do/process/handle だけの名前は避け、対象や目的を具体化
• 引数名と戻り値の名前も「役割が伝わる言葉」に整える
• ドキュメンテーション文字列（docstring）で1行の要約を書くと、より親切

よくあるNGと改善のヒント

実際の現場でよく見かける“惜しい名前”を、改善の観点と合わせて紹介します。 自分のコードに当てはまらないか振り返ってみましょう。

• data, info, value の乱用してしまう→何のデータか具体化（customer_info -> customer_profile, value -> price_yen）
• 変数名に型や属性を示す接頭辞を付けてしまう → Pythonは動的型付け。name_str より name、count_int より count
• 複数形・単数形の混在する → コレクションは複数形（user -> users）、要素は単数形（user）
• 読み手に伝わらない略語　→ 業界標準以外の略語は避ける（cfg -> config、usr -> user）
• 紛らわしい一文字名や似た名前 → l, O, I は単独で使わない。似た名前は区別語を追加（total と totals はNG）

ちょっと実践：名前だけで読みやすくなる

試しに、名前を整えるだけで読みやすさがどう変わるか見てみましょう。

改善前のコードはこちらです。

def f(a):
    b = sum(a)
    c = len(a)
    return b / c

読みやすくするために、以下のように改善します。

def calculate_average(scores):
    total = sum(scores)
    count = len(scores)
    return total / count

関数名と変数名を整えただけで、コードの「意図」が伝わるようになりました。中身のアルゴリズムを変えずに可読性が上がる、命名の力を実感できます。

まとめ

意味のある変数名・関数名は、Pythonの可読性と保守性を大きく左右します。略語に頼らず、真偽値は is_/has_、コレクションは複数形など、小さなルールの積み重ねが“読みやすいコード”を作ります。

「後で読んだ自分は、この名前だけで意味を理解できるか？」と問いかける習慣をつけて、コードを“自己文書化”していきましょう。次のセクションでは、命名と相性の良い「マジックナンバーの排除」について扱います。数字にも名前を与えるコツを学ぶと、さらに読みやすいPythonコードに近づきます。