时间戳

首页 > 解决方案 > 我是否应该记录一个函数的所有参数、异常和返回值，即使它们已经记录在其他函数中？（Python）

python - 我是否应该记录一个函数的所有参数、异常和返回值，即使它们已经记录在其他函数中？（Python）

问题描述

我注意到在许多函数中重复相同的参数。例子：

def run_inspection(first_panel, last_panel, results, settings, references, 
               registration_settings):
"""
Runs multithreading for inspection stage.

Args:
    first_panel (int): Number of the first panel to be inspected.
    last_panel (int): Number of the last panel to be inspected.
    results (data_management.StaticVar): Contains the results string.
    settings (dictionary): General settings dictionary.
    references (list): Contains dictionaries of references data.
    registration_settings (dictionary): Contains data about the registration process.

Raises:
    excepts.FatalError("WRONG_UV_INSPECTION_FLAG"): If the parameter 
        to define if UV light will be used has an incorrect value.

Returns:
    total_time (float): Time it took to create results.
"""

和

def run_debug(first_panel, last_panel, results, settings, references):
"""
Runs multithreading for debug stage.

Args:
    first_panel (int): Number of the first panel to be inspected.
    last_panel (int): Number of the last panel to be inspected.
    results (data_management.StaticVar): Contains the results string.
    settings (dictionary): General configuration dictionary.
    references (list): Contains dictionaries of references data.

Raises:
    excepts.FatalError("WRONG_UV_INSPECTION_FLAG"): If the parameter 
        to define if UV light will be used has an incorrect value.

Returns:
    total_time (float): Time it took to create results.
"""

这些参数在许多功能（超过六个）中不断重复。一些使用这些参数的函数彼此不相关。

我是否应该记录一个函数的所有参数、异常和返回值，即使它们已经记录在许多其他函数中？

标签： pythonparametersdocumentationdocstring

解决方案

是的。

有人怎么会知道在另一个函数中查找该信息？始终将自己置于第一次使用您的包的开发人员的立场上。这正是您的文档很重要的时刻。记住：

您正在为人而不是机器编写代码。为机器编写代码将是二进制的，没有注释。

我喜欢你的问题，因为你触及了 python 文档字符串的一个基本问题：维护相关的文档字符串是乏味且容易出错的。WET 代码的经典示例。

因此，更有趣的问题是如何以一种智能的方式在您的项目中重用文档字符串部分。这在其他 StackOverflow 问题甚至matplotlibGitHub 上的问题中都有讨论：

还有专门针对这个问题的docrep python 包。选择你的毒药;-)

推荐阅读