python/note/python_naming_conventions.md

Python 包、模块、类、函数、变量命名规范

本文档总结 Python 中常见命名规则，便于编写清晰、可维护、符合 PEP 8 的代码。

1. 总体原则

• 命名要清晰、准确、可读
• 优先使用英文单词或英文短语
• 避免使用模糊、不规范的名称
• 保持命名风格统一
• 不要与 Python 内置名称冲突

2. 包（Package）命名规范

规则

• 全部使用小写字母
• 尽量使用简短、表达清晰的词
• 多个单词建议使用下划线连接
• 避免使用大写字母或中文

推荐示例

package_name
user_service
data_utils

不推荐示例

UserService
userService
DATA_UTILS

适用场景

• 目录名
• 项目中逻辑模块的分组名

3. 模块（Module）命名规范

规则

• 全部使用小写字母
• 多个单词用下划线分隔
• 文件名应体现功能或职责
• 以 .py 结尾

推荐示例

user_service.py
math_utils.py
config_loader.py

不推荐示例

UserService.py
userservice.py
mathutils.py

说明

模块名应尽量体现内容，例如：

• user_service.py：用户相关服务
• file_utils.py：文件处理工具
• config_loader.py：配置加载器

4. 类（Class）命名规范

规则

• 使用 PascalCase（大驼峰命名法）
• 每个单词首字母大写
• 类名通常是名词或名词短语

推荐示例

class UserProfile:
    pass

class HttpClient:
    pass

class DataProcessor:
    pass

不推荐示例

class userProfile:
    pass

class http_client:
    pass

说明

类一般用于表示实体、对象或能力集合，例如：

• UserProfile
• OrderService
• FileManager

5. 函数（Function）命名规范

规则

• 使用 snake_case（蛇形命名法）
• 通常是动词或动词短语
• 函数名应该清楚说明作用

推荐示例

def get_user_name():
    pass

def calculate_total():
    pass

def save_to_file():
    pass

不推荐示例

def GetUserName():
    pass

def total():
    pass

说明

函数名通常以“动作”开头，例如：

• read_file()
• send_email()
• validate_password()

6. 变量 / 标量（Variable / Scalar）命名规范

规则

• 使用 snake_case
• 变量名要表达含义，尽量避免单字母（除循环变量外）
• 常量使用大写字母 + 下划线
• 布尔变量前缀常用 is_、has_、can_

推荐示例

user_name = "Tom"
age = 18
total_price = 99.9
is_active = True
has_permission = False

不推荐示例

x = "Tom"
n = 18
a = True

说明

变量名应该尽量说明数据是什么，例如：

• user_name
• max_score
• retry_count
• is_valid

7. 常量（Constant）命名规范

规则

• 全部大写
• 单词之间用下划线连接
• 常量通常在模块级别声明

推荐示例

MAX_RETRY = 5
DEFAULT_TIMEOUT = 30
PI = 3.1415926

不推荐示例

MaxRetry = 5
defaultTimeout = 30

8. 私有命名规范

规则

• 私有变量或函数前加单下划线：_name
• 更强私有时使用双下划线：__secret
• 但不要过度使用双下划线，除非确实需要名称改写

示例

_secret_key = "abc"

class Demo:
    def __private_method(self):
        pass

    def public_method(self):
        self.__private_method()

9. 避免命名冲突

不要使用 Python 内置名称，例如：

list
str
sum
dict
set
int

如果必须使用，建议加上更明确的前后缀，比如：

list_data
user_dict

10. 命名风格一览

类型	命名方式	示例
包	lower_case	data_utils
模块	snake_case	file_handler.py
类	PascalCase	UserManager
函数	snake_case	calculate_total()
变量	snake_case	student_name
常量	UPPER_SNAKE_CASE	MAX_RETRY

11. 推荐命名模板

# 包
package_name

# 模块
module_name.py

# 类
class UserAccount:
    pass

# 函数
def create_user_account():
    pass

# 变量
user_name = "Alice"
account_balance = 1000

# 常量
MAX_LOGIN_ATTEMPTS = 5

12. 最佳实践

• 名称要表意，不要使用无意义缩写
• 优先使用准确、清晰、标准的英文单词
• 统一命名风格，避免混用 camelCase、PascalCase 和 snake_case
• 变量名尽量描述“是什么”，函数名尽量描述“做什么”
• 常量统一使用大写字母加下划线

13. 一句话总结

Python 命名规范的核心是：

• 包：小写，简洁清晰
• 模块：小写下划线，功能导向
• 类：PascalCase，名词化
• 函数：snake_case，动词化
• 变量/标量：snake_case，表达含义
• 常量：UPPER_SNAKE_CASE

遵循这些规则后，代码会更容易阅读、维护和协作。