PythonDocstrings

関数/クラス/メソッド/モジュールの目標を他の人に伝えるだけでなく、自分自身にも伝えるために、ドキュメントは非常に重要です。

今から6か月または12か月後にコードに戻ると、頭の中にあるすべての知識を覚えていない可能性があり、コードを読んでコードが何をするのかを理解するのははるかに困難になります。

コメントはそうするための1つの方法です:

# this is a comment

num = 1 #this is another comment

別の方法は使用することですdocstrings

docstringの有用性は、規則に従うため、自動的に処理できることです。

関数のdocstringを定義する方法は次のとおりです。

def increment(n):
    """Increment a number"""
    return n + 1

これは、クラスとメソッドのdocstringを定義する方法です。

class Dog:
    """A class representing a dog"""
    def __init__(self, name, age):
        """Initialize a new dog"""
        self.name = name
        self.age = age
<span style="color:#66d9ef">def</span> <span style="color:#a6e22e">bark</span>(self):
    <span style="color:#e6db74">"""Let the dog bark"""</span>
    <span style="color:#66d9ef">print</span>(<span style="color:#e6db74">'WOF!'</span>)</code></pre></div>

Document a module by placing a docstring at the top of the file, for example supposing this is dog.py:

"""Dog module

This module does ... bla bla bla and provides the following classes:

- Dog
...
"""

class Dog: “”“A class representing a dog”"" def init(self, name, age): “”“Initialize a new dog”"" self.name = name self.age = age

<span style="color:#66d9ef">def</span> <span style="color:#a6e22e">bark</span>(self):
    <span style="color:#e6db74">"""Let the dog bark"""</span>
    <span style="color:#66d9ef">print</span>(<span style="color:#e6db74">'WOF!'</span>)</code></pre></div>

Docstrings can span over multiple lines:

def increment(n):
    """Increment
    a number
    """
    return n + 1

Python will process those and you can use the help() global function to get the documentation for a class/method/function/module.

For example calling help(increment) will give you this:

Help on function increment in module
__main__:

increment(n) Increment a number

There are many different standards to format docstrings, and you can choose to adhere to your favorite one.

I like Google’s standard: https://github.com/google/styleguide/blob/gh-pages/pyguide.md#38-comments-and-docstrings

Standard allows to have tools to extract docstrings and automatically generate documentation for your code.


More python tutorials: