Python函数：函数文档字符串docstring编写规范

Python函数函数文档字符串docstring编写规范一、开篇代码是写给人看的好的代码自己会说话而docstring文档字符串就是帮代码说话的工具。一个函数如果没有docstring调用者就只能去读源码或者猜它的用法。⌨️ 对比有和没有docstring的区别# ❌ 没有docstring——只能猜defcalc(a,b,mode1):ifmode1:returnabelifmode2:returna-belse:returna*b# ✅ 有docstring——一目了然defcalc(a:float,b:float,mode:int1)-float:对两个数执行指定的运算。 Args: a: 第一个操作数 b: 第二个操作数 mode: 运算模式1加法2减法其他乘法 Returns: 运算结果 Raises: TypeError: 当操作数不是数字时 ifmode1:returnabelifmode2:returna-belse:returna*b docstring是函数、类、模块的使用说明书。更重要的是Python的help()函数和众多文档生成工具都依赖docstring。写好docstring是对自己三个月后的你和同事最大的善意。二、docstring的基本规则2.1 位置和格式# docstring的基本规则# 1. 放在函数/类/模块的第一行def/class之后的第一条语句# 2. 用三引号包裹或# 3. 可以使用多行defgreet(name:str)-str:向指定的人打招呼。returnf你好{name}# 访问docstringprint(greet.__doc__)# 向指定的人打招呼。# help()查看——更友好的展示# help(greet)# 输出# Help on function greet in module __main__:## greet(name: str) - str# 向指定的人打招呼。# ⚠️ docstring必须是字符串字面量不能是变量# def bad():# doc 文档 # 这不是docstring是普通的字符串赋值# pass2.2 单行docstring# 适用场景函数功能简单明了defadd(a:int,b:int)-int:返回a和b的和。returnabdefis_even(n:int)-bool:判断一个整数是否为偶数。returnn%20# PEP 257规范# - 三引号在同一行开始和结束# - 使用句号结尾# - 描述函数的功能做什么而不是实现怎么做# - 使用命令式语气返回...而不是这个函数返回...2.3 多行docstring# 适用场景函数逻辑复杂需要详细说明deffetch_user_data(user_id:int,fields:list[str]|NoneNone,include_inactive:boolFalse,timeout:int30)-dict|None:从数据库获取用户数据。 根据用户ID查询用户信息。如果提供了fields参数 只返回指定的字段。默认不包含已停用的用户。 Args: user_id: 用户唯一标识符 fields: 需要返回的字段列表None表示返回所有字段 include_inactive: 是否包含已停用的用户 timeout: 查询超时时间秒 Returns: 包含用户数据的字典如果用户不存在则返回None。 字典的键取决于fields参数。 Raises: ValueError: 当user_id小于等于0时 TimeoutError: 查询超时时 DatabaseError: 数据库连接失败时 Examples: fetch_user_data(123) {name: 张三, email: zstest.com, age: 25} fetch_user_data(123, fields[name, age]) {name: 张三, age: 25} fetch_user_data(999) None ifuser_id0:raiseValueError(user_id必须大于0)# ... 实际实现 ...return{name:张三,email:zstest.com,age:25}三、三大docstring风格对比3.1 Google风格推荐defsend_notification(user:str,message:str,*,channel:stremail,priority:strnormal,attachments:list[str]|NoneNone,retry_count:int3)-bool:向用户发送通知消息。 支持多种通知渠道消息发送失败时自动重试。 高优先级消息会绕过用户的免打扰设置。 Args: user: 接收通知的用户名或用户ID message: 通知内容支持纯文本 channel: 通知渠道可选值\email\、\sms\、\push\、 \wechat\。默认\email\ priority: 优先级可选值\low\、\normal\、\high\、 \urgent\。默认\normal\ attachments: 附件文件路径列表None表示无附件 默认None retry_count: 失败重试次数默认3 Returns: True表示发送成功False表示所有重试均失败。 Raises: ValueError: 当channel或priority值不合法时 FileNotFoundError: 当附件文件不存在时 Example: send_notification(张三, 您的订单已发货, ... channelsms, priorityhigh) True send_notification(李四, 服务器告警, ... channelpush, priorityurgent) True valid_channels{email,sms,push,wechat}ifchannelnotinvalid_channels:raiseValueError(f无效的通知渠道:{channel})# ... 实际实现 ...returnTrue3.2 NumPy风格defcalculate_statistics(data:list[float],*,skip_na:boolTrue,percentiles:list[int]|NoneNone)-dict:计算数据集的描述性统计。 Parameters ---------- data : list of float 待分析的数据列表。 skip_na : bool, optional 是否跳过NaN值。默认值为True。 percentiles : list of int or None, optional 需要计算的百分位数列表。默认值为None 不计算百分位数。 Returns ------- dict 包含统计结果的字典包含以下键 - count: 样本数量 - mean: 平均值 - std: 标准差 - min: 最小值 - max: 最大值 - percentiles: 百分位数结果如果指定了percentiles Raises ------ ValueError 当data为空列表时。 Examples -------- calculate_statistics([1.0, 2.0, 3.0, 4.0, 5.0]) {count: 5, mean: 3.0, std: 1.58, min: 1.0, max: 5.0} pass3.3 Sphinx/reStructuredText风格defvalidate_email(email:str)-bool:验证邮箱地址格式是否合法。 :param email: 待验证的邮箱地址字符串 :type email: str :return: 邮箱格式合法返回True否则返回False :rtype: bool :raises TypeError: 当email不是字符串时 验证规则 1. 包含恰好一个 符号 2. 前后都有字符 3. 后面部分包含一个 . :: validate_email(userexample.com) True validate_email(invalid-email) False ifnotisinstance(email,str):raiseTypeError(email必须是字符串)partsemail.split()returnlen(parts)2andall(parts)and.inparts[1]3.4 风格选型建议# 风格选择建议## Google风格 → 推荐最流行可读性最好VS Code/PyCharm原生支持# NumPy风格 → 科学计算/数据分析项目首选# Sphinx风格 → 用Sphinx生成文档的项目传统选择## 关键不是用哪种风格而是在项目中保持一致四、docstring在实际开发中的应用4.1 doctest用docstring做测试# doctest模块可以从docstring中提取示例并自动测试defadd(a:int,b:int)-int:返回两个整数的和。 add(2, 3) 5 add(-1, 1) 0 add(0, 0) 0 returnabdeffactorial(n:int)-int:计算n的阶乘。 factorial(0) 1 factorial(1) 1 factorial(5) 120 factorial(-1) Traceback (most recent call last): ... ValueError: n必须是非负整数 ifn0:raiseValueError(n必须是非负整数)ifn1:return1returnn*factorial(n-1)# 运行doctestif__name____main__:importdoctest doctest.testmod()print(所有doctest通过)4.2 模块和类的docstring 用户管理模块 提供用户注册、登录、信息查询和管理功能。 Classes: User: 用户数据模型 UserManager: 用户管理服务 AuthenticationError: 认证异常 Functions: create_user: 创建新用户 authenticate: 验证用户身份 Usage: from user_management import create_user user create_user(zhangsan, password123, ... emailzstest.com) print(user.name) 张三 classUserManager:用户管理服务类。 负责处理用户的创建、查询、更新和删除操作。 所有数据库操作通过此类统一管理。 Attributes: db_connection: 数据库连接对象 cache: 用户信息缓存 max_cache_size: 最大缓存条目数 Example: manager UserManager(db_conn) user manager.get_user(123) manager.update_user(123, {age: 30}) def__init__(self,db_connection):初始化用户管理器。pass五、总结docstring是程序员给未来的自己和同事写的信。好的docstring让代码自带说明书。核心要点所有公共函数/类/模块都应该有docstringPEP 257是Python docstring的官方规范Google风格是目前最流行的选择doctest让docstring既是文档又是测试一致性比风格更重要——项目内统一风格✅docstring应该写什么函数做什么不是怎么做参数的含义和类型返回值的含义可能抛出的异常简单的使用示例❌docstring不应该写什么显而易见的实现细节版本历史交给git谁写的、什么时候写的交给git blame