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

Question

我注意到在许多函数中相同的参数会重复。示例:

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.
"""

这些参数在许多函数(超过六个)中不断重复。 某些使用这些参数的函数彼此不相关。

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

Answer 1

是的。

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

You are writing code for people and not machines. Writing code for machines would be binary without comments.

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

因此，更有趣的问题是如何以智能方式在项目中重用文档字符串部分。这在其他 StackOverflow 问题甚至 GitHub 上的 matplotlib 问题中进行了讨论:

• Repetitive Content in Docstrings
• Including a docstring in another docstring
• Inherit docstrings in Python class inheritance
• Reuse docstring from a method in a class in python
• How to best handle repeating docstrings

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