Pythonのdocstringの書き方

全般

• docstringは可能な限り省略する。
• docstringは面倒でもしっかり書く。
• docstringの上下には空行を入れない。

一つ目と二つ目は矛盾して聞こえるかもしれないが、これは要するに、必要最低限の内容を書くということ。多すぎるのも、少なすぎるのもダメだということだ。多すぎるとソースコードが読みにくくなり、少なすぎるとソースコードが再利用しづらくなる。

ただ、多いのと少ないのとどちらがマシかといえば多い方がマシだ。省略しても良いか迷うくらいなら、書いておいた方が良い。

ただし、再利用することがないと思うソースコードに関しては、docstringをつけるのは無駄骨なのでしなくて良い。再利用することがわかった時点で書けば良い。

あの怠惰なプログラマの腕が良いのは、最小の労力で最大の結果を引き出そうとしているからだ。

クラス

class Cls:
    """
    <explanation>
    """

内容

• クラスの説明の一文目は、クラス名で始まる、クラス名が主語の文にする。
• 自明な説明は省略しても良い。

形式

• クラスの説明を省略するときは、docstringそのものを省略する。

例

class Person:
    """
    Person represents a person.
    """
    """
    self.name str:
        self.name is a name of <self>.
    """
    def __init__(self):
        pass

    def __str__(self):
        return f"My name is {self.name}."

    def setName(self, name):
        """
        Args:
            name str:
        """
        self.name = name

メソッド

以下の点を除いて、関数の場合と同じ。

内容

• インスタンスメソッドおよびクラスメソッドの第一引数の説明は完全に省略する。
• __init__がself以外の引数を取らないなら、そのdocstringは完全に省略する。
• __str__などの用途が決まっている特殊なメソッドにはdocstringを書かない。

フィールド

以下の点を除いて、変数の場合と同じ。

内容

• 説明の中では、自身のインスタンスは<self>と表す。
• インスタンス変数については、クラスの説明のすぐ下にまとめて書く。
• クラス変数については、定義部に書く。

関数

def func(...):
    """
    <explanation>

    Args:
        <name> <type>:
            <explanation>

        ...

    Returns:
        <type>:
            <explanation>

        ...

    Errors:
        <type>:
            <explanation>

        ...
    """

内容

• 説明の中で、引数の値は<引数名>と表す。
• 関数の説明(冒頭の説明)の一文目は、関数名で始まる、関数名が主語の文にする。
• 関数の説明は、関数がどのような処理を行うかを説明する。
• Argsの説明の一文目は引数名で始まる、引数名が主語の文にする。
• ArgsとReturnsの説明は、引数や返り値が何を表すかを表すかを説明する。
• Errorsの説明の一文目は、エラーの型で始まる、エラーの型が主語の文にする。
• Errorsの説明は、そのエラーがいつ起こるのかを説明する。
• 自明な説明は省略しても良い。

形式

• Args、Returns、Errorsの説明は、各要素(引数、返り値、エラー)の説明の間には空行を入れる。
• 関数の説明を省略するときは、上に詰める。
• Args、Returns、Errorsの説明を省略するときは、空行にして開けておく。

型の表示

型名	記法
primitive	<primitive name>
class	<class name>
list	[<value type>]
tuple	(<value type>)
set	{<value type>}
dict	{<key type>:<value type>}

注釈

• <value type>と<key type>には、再帰的に型記法が入る。
• primitiveとは、int、float、bool、strのこと。
• classとは、primitive以外の、classに基づく型のこと。
• 自作クラスの場合は、トップレベルパッケージから書く。

型記法の例

[[int]]

intの二重リスト

例: [[1, 2, 3], [4, 5, 6]]

{str: bool}

キーがstrで値がboolの辞書

例: {"isPython": True, "isRuby": False, "isJavascript": False}

例

def isLargerThan(ln, rn):
    """
    Args:
        ln int:

        rn int:

    Returns:
        bool:
            Represent if <ln> is larger than <rn>.
            True: <ln> is larger than <rn>
            False: <ln> is equal to or less than <rn>
    """
    return ln > rn

変数

"""
<var name> <type>:
    <explanation>

...
"""

内容

• 変数の説明の一文目は変数名で始まる、変数名が主語の文にする。
• 複数の変数の説明をまとめてしても良い。
• 自明な説明は省略しても良い。

形式

• 変数の説明をまとめてする時の説明の順番は、変数が定義されている順番通りにする。
• 変数の説明をまとめてする時は、各変数の説明の間には空行を入れる。
• 変数の説明を省略するときは、上に詰めるか空行にする。

例

"""
name str:
    name is the name of Alice.

age int:
    age is the age of Alice.

sex str:

"""
name = "Alice"
age = 20
sex = "Female"