Python之變量命名規(guī)則詳解
在 Python 編程中,變量命名看似是 “小事”,卻直接影響代碼的可讀性、可維護(hù)性,甚至團(tuán)隊(duì)協(xié)作效率。
糟糕的命名會(huì)讓后續(xù)調(diào)試、迭代變得舉步維艱 —— 想想看,當(dāng)你接手一個(gè)包含a1、str_1、func_x這類變量的項(xiàng)目時(shí),是不是要花大量時(shí)間猜測(cè)它們的用途?
這篇文章將從 “基礎(chǔ)規(guī)則” 到 “進(jìn)階規(guī)范”,結(jié)合 “三要三不要” 原則,避開常見坑。
1. 硬性規(guī)則
在談 “規(guī)范” 之前,必須先明確 Python 語(yǔ)法層面的 “強(qiáng)制要求”—— 違反這些規(guī)則,代碼會(huì)直接報(bào)錯(cuò),根本無(wú)法運(yùn)行。
只能包含字母、數(shù)字和下劃線變量名的第一個(gè)字符必須是字母(a-z, A-Z)或下劃線(_),不能以數(shù)字開頭。
- ? 合法:
user_name、age_18、_total_score - ? 非法:
18_age(以數(shù)字開頭)、user-name(包含連字符)、user@name(包含特殊符號(hào))
區(qū)分大小寫Python 對(duì)大小寫敏感,User和user是兩個(gè)完全不同的變量。示例:
user = "Lyle" User = "Tom" print(user) # 輸出:Lyle print(User) # 輸出:Tom
不能使用關(guān)鍵字 / 保留字關(guān)鍵字是 Python 內(nèi)置的、有特殊含義的單詞(如if、for、class等),不能作為變量名。如何查看所有關(guān)鍵字?可以用以下代碼:
import keyword print(keyword.kwlist) print(len(keyword.kwlist)
['False', 'None', 'True', 'and', 'as', 'assert', 'async', 'await', 'break', 'class', 'continue', 'def', 'del', 'elif', 'else', 'except', 'finally', 'for', 'from', 'global', 'if', 'import', 'in', 'is', 'lambda', 'nonlocal', 'not', 'or', 'pass', 'raise', 'return', 'try', 'while', 'with', 'yield'] 35
? 錯(cuò)誤示例:if = 10(if是關(guān)鍵字)、class = "學(xué)生"(class是關(guān)鍵字)
2. “三要” 原則
語(yǔ)法規(guī)則保證代碼能運(yùn)行,而 “三要” 原則則保證代碼 “好讀、好維護(hù)”。核心思路是:讓變量名 “自解釋”,減少注釋依賴。
2.1. 要體現(xiàn)變量的 “實(shí)際作用”,拒絕 “無(wú)意義命名”
如果一個(gè)變量名只能告訴你 “它是個(gè)字符串” 或 “它是個(gè)數(shù)字”,卻無(wú)法說明 “它存的是什么內(nèi)容”,那就是無(wú)效命名。
? 反面示例:str_1、num_1分別存的是什么?—— 需要猜!
str_1 = "zhangsan@example.com"
num_1 = 25
print(f"用戶信息:{str_1}, {num_1}")
? 正面示例:一看就知道存的是“用戶郵箱”和“用戶年齡”
user_email = "zhangsan@example.com"
user_age = 25
print(f"用戶信息:{user_email}, {user_age}")
2.2. 要讓變量名 “自解釋”,減少注釋依賴
如果一個(gè)變量需要額外加注釋才能說明用途,說明命名效率極低 —— 工程變大后,變量可能出現(xiàn)在多個(gè)文件中,注釋容易遺漏或過時(shí),導(dǎo)致可讀性驟降。
? 反面示例(依賴注釋):
# 注釋:這個(gè)變量存的是用戶是否已實(shí)名認(rèn)證(True=已認(rèn)證,F(xiàn)alse=未認(rèn)證) user_flag: bool = True # 問題:flag太泛,沒有說明“什么flag”
? 正面示例(自解釋,無(wú)需注釋):
# 優(yōu)點(diǎn):變量名直接說明“用戶是否已實(shí)名認(rèn)證”,無(wú)需額外注釋 user_is_certified: bool = True
2.3. 函數(shù)命名要 “明確功能”,不要怕 “長(zhǎng)”
函數(shù)名的核心是 “說明它做什么”,而不是 “它是什么類型”。很多新手怕函數(shù)名太長(zhǎng),用func1、do_something這類泛泛的名字,反而增加理解成本 ——清晰比簡(jiǎn)短更重要。
? 反面示例:
# 問題:func1做什么?需要讀函數(shù)內(nèi)部代碼才知道
def func1(data):
return [x for x in data if x > 60]
# 調(diào)用時(shí)一臉懵:傳什么data?返回什么結(jié)果?
result = func1([85, 40, 72, 58])
? 正面示例:
# 優(yōu)點(diǎn):函數(shù)名直接說明“篩選列表中大于60的元素”
def filter_scores_above_60(scores):
return [score for score in scores if score > 60]
# 調(diào)用時(shí)一目了然:傳“分?jǐn)?shù)列表”,得“及格分?jǐn)?shù)”
passed_scores = filter_scores_above_60([85, 40, 72, 58])
print(passed_scores) # 輸出:[85, 72]
3. “三不要” 原則(??避坑指南)
除了 “要做什么”,更要明確 “不要做什么”—— 這些細(xì)節(jié)容易被忽略,卻會(huì)讓代碼變得混亂。
3.1. 不要 “自造縮寫”
縮寫的目的是簡(jiǎn)化命名,而不是制造 “密碼”。如果你的縮寫只有自己能懂,團(tuán)隊(duì)其他人需要花時(shí)間猜測(cè),就失去了意義。必須使用行業(yè)或 Python 社區(qū)通用的縮寫。
? 反面示例(自造縮寫):
# 問題:nm和thrs是什么?第一次接觸代碼的成員可能看不懂 nm: str = 'Lyle' thrs: float = 30.0 # 自造:thrs=threshold pwd = "123456" # 自造:pwd=password(雖常見,但建議寫全password更清晰)
? 正面示例(通用縮寫):
# 通用縮寫:id(identity)、url(Uniform Resource Locator)、http(HyperText Transfer Protocol) user_id: str = "1001" user_password: str = "123456" # 密碼建議寫全,避免歧義 config_path: str = "config.ini" # 復(fù)雜場(chǎng)景可用通用縮寫(如API、SDK) api_key: str = "abc123def456" sdk_version: str = "3.8.0"
3.2. 不要忽略 “英文語(yǔ)法”,注意單復(fù)數(shù)、動(dòng)名詞
變量名的語(yǔ)法錯(cuò)誤會(huì)傳遞錯(cuò)誤信息 —— 比如用單數(shù)表示 “多個(gè)元素”,用名詞表示 “一個(gè)動(dòng)作”,都會(huì)誤導(dǎo)。
? 反面示例(語(yǔ)法錯(cuò)誤):
# 問題1:user存的是列表(多個(gè)用戶),卻用單數(shù)
user = ["Lyle", "Tom", "Jerry"]
print(f"用戶數(shù)量:{len(user)}") # 邏輯上沒問題,但語(yǔ)法誤導(dǎo)
# 問題2:get_user是“獲取用戶”的動(dòng)作,卻用來存“用戶信息”(名詞)
get_user = "Tony"
# 問題3:calculate_total是動(dòng)詞短語(yǔ),卻用來存“結(jié)果”(名詞)
calculate_total = 1500 # 實(shí)際是“總金額”
? 正面示例(語(yǔ)法正確):
# 規(guī)則1:?jiǎn)螖?shù)表“單個(gè)”,復(fù)數(shù)表“多個(gè)”
users = ["Lyle", "Tom", "Jerry"] # 列表用復(fù)數(shù)
print(f"用戶數(shù)量:{len(users)}")
# 規(guī)則2:變量用“名詞”,函數(shù)用“動(dòng)詞/動(dòng)名詞”(表動(dòng)作)
user_info = "Tony" # 變量:名詞(用戶信息)
total_amount = 1500 # 變量:名詞(總金額)
# 規(guī)則3:函數(shù)用“動(dòng)詞開頭”(如get_、filter_、calculate_)表動(dòng)作
def get_user_info(user_id): # 函數(shù):動(dòng)詞(獲取用戶信息)
return f"用戶ID {user_id} 的信息"
3.3. 不要 “濫用下劃線”,避免過長(zhǎng)或冗余
下劃線是 Python 推薦的 “蛇形命名法”(snake_case)的核心,但不是越多越好。冗余的下劃線會(huì)讓變量名變長(zhǎng),反而降低可讀性。
? 反面示例(濫用下劃線):
# 問題1:冗余的“_of”“_for”,可簡(jiǎn)化 user_name_of_student = "Lyle" # 簡(jiǎn)化為 student_name score_list_for_math = [90, 85, 92] # 簡(jiǎn)化為 math_scores # 問題2:無(wú)意義的前綴,增加長(zhǎng)度 var_user_age = 20 # 前綴var_毫無(wú)意義,直接用user_age data_order_total = 300 # 前綴data_冗余,直接用order_total
? 正面示例(簡(jiǎn)潔合理):
student_name = "Lyle" math_scores = [90, 85, 92] user_age = 20 order_total = 300
4. QA
4.1. 變量名用 “蛇形命名法” 還是 “駝峰命名法”?
Python 官方推薦蛇形命名法(snake_case,全小寫 + 下劃線分隔),適用于變量、函數(shù)、模塊;而駝峰命名法(CamelCase,首字母大寫)主要用于類名(如UserInfo、StudentScore)。
示例:
# 蛇形命名法(變量、函數(shù))
user_address = "北京市朝陽(yáng)區(qū)"
def calculate_discount(price):
return price * 0.8
# 駝峰命名法(類名)
class UserInfo:
def __init__(self, name, age):
self.name = name
self.age = age
4.2. 什么時(shí)候用 “單下劃線開頭” 的變量(如_user_name)?
這是 Python 的 “約定俗成”,表示該變量是 “內(nèi)部變量”,不建議外部直接訪問(類似其他語(yǔ)言的 “私有變量”)。雖然語(yǔ)法上不強(qiáng)制限制,但能提醒其他開發(fā)者 “不要隨便修改”。
示例:
class Student:
def __init__(self, name, score):
self.name = name # 公開變量,外部可訪問
self._score = score # 內(nèi)部變量,建議外部通過方法訪問
# 外部通過這個(gè)方法獲取分?jǐn)?shù),而不是直接訪問_score
def get_score(self):
return self._score
4.3. 變量名太長(zhǎng)怎么辦?
比如有一個(gè)變量的名稱為calculate_monthly_user_payment_total。
首先,“長(zhǎng)” 不是問題,“不清晰” 才是問題。如果確實(shí)過長(zhǎng),可以通過以下方式優(yōu)化:
- 檢查是否有冗余詞(如
calculate可簡(jiǎn)化為calc,但需團(tuán)隊(duì)認(rèn)可); - 拆分邏輯(比如將復(fù)雜計(jì)算拆成多個(gè)小函數(shù),變量名自然簡(jiǎn)化)。示例優(yōu)化:
Tip:Apple公司的變量名和函數(shù)名都非常長(zhǎng),但卻得到很多人的認(rèn)可
# 原長(zhǎng)變量名
calculate_monthly_user_payment_total = 5000
# 優(yōu)化:拆分邏輯,變量名更簡(jiǎn)潔
def calc_user_payment(monthly_fee):
return monthly_fee * 12 # 假設(shè)年付是月付的12倍
user_yearly_payment = calc_user_payment(5000) # 簡(jiǎn)化為“用戶年付款”
4.4. 可以用中文作為變量名嗎?
考慮到代碼的一致性,不推薦使用中文命名,但如有必要也可以使用中文進(jìn)行命名
5. 總結(jié)
最后,用一句話總結(jié) Python 變量命名的核心:讓變量名像 “說明書” 一樣清晰,讓別人(包括 3 個(gè)月后的你)看一眼就知道它的用途。
記住三個(gè)核心點(diǎn):
- 先遵守 “硬性規(guī)則”(字母 / 數(shù)字 / 下劃線、區(qū)分大小寫、不碰關(guān)鍵字);
- 再踐行 “三要”(體現(xiàn)作用、自解釋、函數(shù)名明確);
- 避開 “三不要”(不造縮寫、不忽略語(yǔ)法、不濫用下劃線)。
以上為個(gè)人經(jīng)驗(yàn),希望能給大家一個(gè)參考,也希望大家多多支持腳本之家。
相關(guān)文章
如何在PyCharm中安全地設(shè)置和使用API Key方式
在PyCharm中,通過運(yùn)行配置添加API_KEY環(huán)境變量,使用os.environ或os.getenv在代碼中引用,確保安全性,避免硬編碼,推薦設(shè)置默認(rèn)值或提示2025-07-07
Python實(shí)現(xiàn)的掃碼工具居然這么好用!
二維碼作為一種信息傳遞的工具在當(dāng)今社會(huì)發(fā)揮了重要作用.從手機(jī)用戶登錄到手機(jī)支付,生活的各個(gè)角落都能看到二維碼的存在.那你知道二維碼是怎么解析的嗎?有想過自己實(shí)現(xiàn)一個(gè)掃碼工具嗎?如果想的話就繼續(xù)看下去吧!需要的朋友可以參考下2021-06-06
python networkx 包繪制復(fù)雜網(wǎng)絡(luò)關(guān)系圖的實(shí)現(xiàn)
這篇文章主要介紹了python networkx 包繪制復(fù)雜網(wǎng)絡(luò)關(guān)系圖的實(shí)現(xiàn),文中通過示例代碼介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或者工作具有一定的參考學(xué)習(xí)價(jià)值,需要的朋友們下面隨著小編來一起學(xué)習(xí)學(xué)習(xí)吧2019-07-07
pytorch中函數(shù)tensor.numpy()的數(shù)據(jù)類型解析
這篇文章主要介紹了pytorch中函數(shù)tensor.numpy()的數(shù)據(jù)類型,具有很好的參考價(jià)值,希望對(duì)大家有所幫助。如有錯(cuò)誤或未考慮完全的地方,望不吝賜教2022-07-07
Django實(shí)現(xiàn)WebSocket在線聊天室功能(channels庫(kù))
本文基于channels庫(kù)Django實(shí)現(xiàn)WebSocket在線聊天室功能,包括安裝及創(chuàng)建django項(xiàng)目的全過程,通過實(shí)例代碼給大家介紹的非常詳細(xì),對(duì)大家的學(xué)習(xí)或工作具有一定的參考借鑒價(jià)值,需要的朋友可以參考下2021-09-09
Python連接KingbaseES數(shù)據(jù)庫(kù)完整指南
本文詳細(xì)介紹了如何使用psycopg2連接KingbaseES數(shù)據(jù)庫(kù),包括環(huán)境準(zhǔn)備、基本連接、執(zhí)行查詢和數(shù)據(jù)操作、連接池使用、大對(duì)象處理以及常見問題排查,感興趣的朋友跟隨小編一起看看吧2026-01-01
對(duì)python過濾器和lambda函數(shù)的用法詳解
今天小編就為大家分享一篇對(duì)python過濾器和lambda函數(shù)的用法詳解,具有很好的參考價(jià)值,希望對(duì)大家有所幫助。一起跟隨小編過來看看吧2019-01-01
Python Pydantic數(shù)據(jù)驗(yàn)證的實(shí)現(xiàn)
本文主要介紹了Python Pydantic數(shù)據(jù)驗(yàn)證的實(shí)現(xiàn)2025-04-04

