如何编写有意义的docstrings？ [英] How to write meaningful docstrings?

问题描述

什么，在你看来是一个有意义的docstring？

例如，考虑这个Python类的 __ init __ ：

  def __init __（self，name，value，displayName = None，matchingRule =strict）：

 name  - 字段名
 value  - 字段值
 displayName  -  nice显示名称，如果为空，将设置为字段名称
 matchingRule  - 我不知道这是什么，默认设置为strict 

  

解决方案

我同意任何你不能从方法的签名告诉。

您可能还需要使用 Sphinx （和reStructuredText语法），以便在docstrings中进行文档编制。这样，您可以轻松地将它包括在您的文档中。例如， repoze.bfg 广泛使用此功能（示例文件，文档示例） http://docs.python.org/library/doctest.html =nofollow noreferrer> doctests 。这可能有意义esp。对于模块或类的文档字符串，你也可以显示如何使用它，并有可测试的同时。

What, in Your opinion is a meaningful docstring? What do You expect to be described there?

For example, consider this Python class's __init__:

def __init__(self, name, value, displayName=None, matchingRule="strict"):
    """
    name - field name
    value - field value
    displayName - nice display name, if empty will be set to field name
    matchingRule - I have no idea what this does, set to strict by default
    """

Do you find this meaningful? Post Your good/bad examples for all to know (and a general answer so it can be accepted).

解决方案

I agree with "Anything that you can't tell from the method's signature". It might also mean to explain what a method/function returns.

You might also want to use Sphinx (and reStructuredText syntax) for documentation purposes inside your docstrings. That way you can include this in your documentation easily. For an example check out e.g. repoze.bfg which uses this extensively (example file, documentation example).

Another thing one can put in docstrings is also doctests. This might make sense esp. for module or class docstrings as you can also show that way how to use it and have this testable at the same time.

这篇关于如何编写有意义的docstrings？的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！