有啥理由将代码放在 Python 中的文档字符串之前？

Posted 2023-04-18

【中文标题】有啥理由将代码放在 Python 中的文档字符串之前？

【英文标题】：Any reason to put code before the docstring in Python?有什么理由将代码放在 Python 中的文档字符串之前？

【发布时间】：2016-09-01 07:52:39

【问题描述】：

我在其他人的 Python 代码中看到他们在函数的文档字符串之前粘贴了一些检查；像这样：

def func(args):
  if x_version != 1.7:
    return
  """docstring is here"""
  # function body code
  # ...

是否存在您应该或必须在文档字符串之前放置一些代码以解决任何问题的情况？是否有任何特殊情况必须引入这种样式，或者它总是只是一种不好的样式，因此必须固定为这样的东西？

def func(args):
  """docstring is here"""
  if x_version != 1.7:
    return
  # function body code
  # ...

【参考方案1】：

如果是函数体中的 first 语句，Python 只会选择一个文档字符串。将代码放在它之前意味着该字符串将被完全忽略：

>>> def func(args):
...   if x_version != 1.7:
...     return
...   """docstring is here"""
...
>>> func.__doc__ is None
True

如果您希望文档字符串真正发挥作用，您应该从不这样做。

来自Python reference documentation：

作为函数主体中的第一条语句出现的字符串文字被转换为函数的__doc__ 属性，从而转换为函数的文档字符串。

我的大胆强调。

【讨论】：

确实如此。我正在使用inspect 模块来查看是否有没有文档字符串的函数，这就是我找到带有移动文档字符串的函数的方法:) 所以当你必须在之前放置任何 Python 代码时，你不会想到任何特殊情况文档字符串（了解文档字符串在 IDE 等中对其他人不可用）？

@AlexTereshenkov：粗心大意和“哦，对不起，我不知道”可能属于特殊情况。

@AlexTereshenkov：从不有这样做的理由。认为这是一个错误。

太棒了，谢谢。想在编辑别人的代码之前先检查一下，以免搞砸。

@AlexTereshenkov：有些人确实使用三引号字符串来“注释掉”一段代码，因为如果不是第一个语句，CPython 将完全忽略独立的字符串文字，但我通常建议人们改为使用普通评论（您的编辑可以提供帮助）。