如何同步Python脚本与模块的文档字符串并减少重复？

核心思路 #

只维护一处描述文本，其他场景（模块文档、main函数文档、argparse参数）都直接引用这个来源，彻底消除重复。

方案1：以模块级文档字符串为唯一来源 #

把脚本最顶部的模块文档字符串作为统一描述源，其余地方直接复用：

#!/usr/bin/env python3
"""
My long description
支持多行内容，
可以包含脚本的功能说明、使用场景等所有细节
"""

import argparse

def main():
    """
    __doc__
    """
    # 用strip()去除首尾空白，适配命令行输出格式
    parser = argparse.ArgumentParser(description=__doc__.strip())
    # 后续参数解析逻辑
    args = parser.parse_args()

if __name__ == "__main__":
    main()

• 唯一需要修改的地方就是模块顶部的三重引号内容
• main函数的文档字符串直接复用模块的__doc__属性，查看函数文档时会自动解析显示完整描述
• argparse直接调用__doc__.strip()来调整格式，避免多余的换行影响命令行帮助输出

方案2：定义单独描述常量（适配灵活格式需求） #

如果需要给不同场景提供略有差异的描述（比如main函数要加额外运行说明），可以先定义一个基础常量，再基于它生成其他文本：

#!/usr/bin/env python3
import argparse

# 唯一需要维护的描述源
BASE_DESCRIPTION = """My long description"""

# 模块文档字符串直接赋值
__doc__ = BASE_DESCRIPTION

def main():
    """
    {BASE_DESCRIPTION}
    
    额外说明：此函数为脚本入口，负责解析命令行参数并执行核心逻辑
    """.format(BASE_DESCRIPTION=BASE_DESCRIPTION)
    parser = argparse.ArgumentParser(description=BASE_DESCRIPTION)
    args = parser.parse_args()

if __name__ == "__main__":
    main()

• 只需要更新BASE_DESCRIPTION，模块文档、main函数文档、argparse描述都会同步变化
• 可以基于基础常量扩展不同场景的描述内容，同时保证核心信息一致

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