函数层面
- 文档字符串：使用三重引号（
"""）在函数定义的下一行编写文档字符串。
- 第一行：简要描述函数的功能，例如：
"""计算两个数的和。"""
- 后续行：详细描述函数的参数、返回值及可能引发的异常等。例如：
def add_numbers(a, b):
"""
计算两个数的和。
:param a: 第一个数字，int或float类型。
:param b: 第二个数字，int或float类型。
:return: a 和 b 的和，类型与输入参数相同。
"""
return a + b
- 注释：在代码逻辑复杂的地方添加注释，解释代码的作用，如：
def complex_function(x):
# 对输入值进行平方
result = x ** 2
# 根据平方结果进行条件判断
if result > 100:
return result - 100
else:
return result
类层面
- 文档字符串：同样在类定义下一行使用三重引号。
- 第一行：简要描述类的用途，如：
"""表示一个用户对象。"""
- 后续行：描述类的属性、方法及类的整体行为，例如：
class User:
"""
表示一个用户对象。
Attributes:
name (str): 用户的名字。
age (int): 用户的年龄。
Methods:
get_info(): 返回用户的信息字符串。
"""
def __init__(self, name, age):
self.name = name
self.age = age
def get_info(self):
return f"Name: {self.name}, Age: {self.age}"
- 注释：在类方法内部逻辑复杂处添加注释，类似函数注释方式。
模块层面
- 文档字符串：在模块的开头（所有导入语句之后）使用三重引号。
- 第一行：简要说明模块的功能，如：
"""提供用户管理相关的功能。"""
- 后续行：详细描述模块的功能、包含的类和函数以及模块的使用场景等，例如：
"""
提供用户管理相关的功能。
该模块包含了用于创建、查询和删除用户的函数和类。
主要类:
User: 表示用户对象。
主要函数:
create_user(): 创建新用户。
delete_user(): 删除指定用户。
"""
from user_class import User
def create_user(name, age):
return User(name, age)
def delete_user(user):
# 实际实现可能涉及数据库操作等
pass
- 注释：在模块内，对重要的代码块或逻辑进行注释，帮助理解模块整体架构。
保证规范有效执行的工具和流程
- 工具
- flake8：可通过配置文件设置注释相关规则，如检查文档字符串是否缺失等。安装后在项目根目录运行
flake8命令即可检查代码是否符合规范。
- pydocstyle：专门用于检查Python文档字符串是否符合规范。可以通过
pip install pydocstyle安装，然后运行pydocstyle命令检查项目代码。
- 流程
- 代码审查：在代码合并到主分支前，进行人工代码审查，确保注释符合规范。
- 持续集成（CI）：将注释规范检查工具集成到CI流程中，如在GitHub Actions、GitLab CI/CD等平台配置任务，每次代码推送或合并请求时自动运行检查工具，若不符合规范则阻止合并。
