Python跨多函数的共用参数如何规范编写文档

针对a、b、c这类多层调用、透传统一配置参数的函数场景，核心要解决的问题是避免重复复制粘贴参数说明导致的多版本不一致，可以按以下规则落地：

核心原则 #

• 函数独有的业务参数（比如a的a1/a2、b的b1、c的c1/c2/c3）：必须在所属函数的文档字符串中单独说明含义、取值要求、触发逻辑，这类参数是上层函数独有的业务逻辑，不能复用其他位置的文档。
• 全链路透传的共用参数（p1/p2/p3）：将参数的唯一定义锚定在真正实现参数对应逻辑的最底层函数（也就是本例中的a），所有上层传递这些参数的函数，不再重复编写和底层完全一致的参数说明，从根源上减少多份文档的同步成本。

具体低维护实现 #

最稳妥、对IDE和文档工具兼容性最好的方式，是将共用参数的说明提取为模块级的可复用字符串常量，各个函数直接引用拼接，不需要逐处复制修改：

# 模块顶层维护所有共用参数的文档片段，仅需修改这一处
_DOC_P1 = """:param p1: 控制输出编码格式的开关，可选值为 ["a", "b"]，默认值"a""""
_DOC_P2 = """:param p2: 控制结果排序方向的配置，可选值为 ["b", "c"]，默认值"b" """
_DOC_P3 = """:param p3: 控制结果截断长度的正整数参数，默认值3"""


def a(a1, a2, p1="a", p2="b", p3=3):
    """
    :param a1: 第一维度业务入参，不可为空
    :param a2: 第二维度业务入参，不可为空
    """ + _DOC_P1 + _DOC_P2 + _DOC_P3


def b(b1, p1="a", p2="b", p3=3):
    """
    :param b1: 业务线标识入参，用于匹配对应数据规则
    """ + _DOC_P1 + _DOC_P2 + _DOC_P3
    ...
    return a(a1, a2, p1, p2, p3)


def c(c1, c2, c3, p1="a", p2="b", p3=3):
    """
    :param c1: 页面请求上下文入参
    :param c2: 用户身份标识入参
    :param c3: 操作场景标记入参
    """ + _DOC_P1 + _DOC_P2 + _DOC_P3
    ...
    b(b1, p1, p2, p3)
    ...

配套落地规则 #

• 全链路透传的共用参数，禁止在上层函数（b、c）中随意修改参数语义、默认值、取值范围。如果需要调整，统一修改模块顶层的文档常量、以及所有传递位置的参数默认值，保证文档和逻辑始终对齐。
• 如果某个上层函数对共用参数有特殊限制（比如c函数场景下p1不允许传"b"），不要修改全局的共用文档常量，仅在当前函数的文档末尾追加补充说明即可：

  注：本函数运行场景下p1参数仅支持传入"a"，传入其他值会触发参数校验错误。

• 不推荐用装饰器动态生成docstring的方案——这类方案虽然也能实现复用，但会导致IDE无法正常识别函数的参数提示，反而降低日常开发体验。
• 只有当参数在全调用链的语义、默认值、取值范围完全一致时，才纳入统一文档常量的管理，存在场景差异的参数必须单独编写说明，不要为了复用强行合并。

内容的提问来源于stack exchange，提问作者Diamond