Python で最も一般的な Docstring パターン

コードを文書化することは良い習慣であり、意欲的な開発者とプログラマーは、コーディングの旅の初期段階でコードを文書化する習慣を身に付ける必要があります。

ソースコードを文書化すると、ソースコードの可読性と管理が向上し、ソースコードへの新しい貢献者がソースコードを非常に簡単に理解できるようになります。

Docstring は、ソースコード内に記述された文字列リテラルです。これらは、コードの一部に対するコメントまたはドキュメントとして機能します。Docstring は、クラス、関数、場合によってはファイルを記述するために使用されます。

つまり、docstring はコードスニペットに関するメタデータとして機能します。docstring には、説明内容に関するすべての関連情報が含まれています。クラスの場合、次の情報を保持します。

• クラス
• クラス関数
• クラス属性

関数については、以下に関する詳細が保持されます。

• パラメーター
• パラメータのデータ型
• パラメータのデフォルト値
• パラメータに関する簡単な説明
• 関数が返すもの
• 関数によって返されるもののデータ型
• 関数が発生するエラーと例外、および

プロの Python 開発者がコードを文書化するために使用する docstring パターンがいくつかあります。

既存のものを使用する代わりに、それらの docstring パターンを作成することができます。それでも、この決定は、個々の開発者または開発者のチームにのみ依存します。

この記事では、Python プログラミング言語に最適な docstring パターンに取り組みます。

Python の Docstring パターン

以下は、Python の専門家が業界で一般的に使用している最高の docstring パターンの一部です。

Epytext パターン

Epytext パターンは、JavaDoc に似た docstring パターンです。これは、Docstring を使用して Python モジュールのドキュメントを生成するために使用される Epydoc ツールの一部です。以下は、Epytext パターンの例です。

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

@param parameter1: this is the first parameter.
@param parameter2: this is the second parameter.
@return: this is a description of what is returned by the function.
@raise KeyError: raises an exception.
@raise TypeError: raises an exception.
"""

機能の簡単な説明は上部にあります。

すべての関数パラメーターは、@param キーワードを使用して記述されています。関数によって返されるものの説明は、@return キーワードの横に書かれています。

関数がエラーまたは例外を発生させる場合、それらは@raise キーワードを使用して記述されます。

reST パターン

reSt または reStructuredText は、Python プログラミング言語のドキュメントを生成するためのツールである Sphinx で使用される docstring パターンです。このパターンは、IT 業界で最も使用されている docstring パターンの 1つです。

このメソッドは、Python プログラマーが docstring を使用して拡張コードドキュメントを作成するのに役立つツールである Pyment の出力形式としても使用されます。このツールは、コードが部分的に文書化されているか、docstring が含まれていない場合に役立ちます。

JetBrains PyCharmIDE または統合開発環境も reST パターンを使用します。以下は、reST パターンの例です。

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

:param parameter1: this is the first parameter.
:param parameter2: this is the second parameter.
:return: this is a description of what is returned by the function.
:raise KeyError: raises an exception.
:raise TypeError: raises an exception.
"""

Epytext パターンと同様に、このパターンでもすべて同じですが、アットマークや Epytext パターンの場合は@の代わりに、キーワードのプレフィックスとしてコロンまたは:を使用します。

メソッドの簡潔または包括的な説明が上部にあります。すべてのパラメータは、:param キーワードの隣にあります。メソッドによって返されるものの説明は、:return キーワードの横に書かれています。

また、すべてのエラーの詳細は、:raise キーワードの横に表示されます。

Google パターン

リストのもう 1つのパターンは、Google のパターンです。技術的には、その名前は Google のパターンではありませんが、Google が開発したパターンです。

見出しの下に詳細を整理するきれいなパターンです。Sphinx ツールは、このパターンも認識してドキュメントを生成することができます。

このパターンは、最も docstrings パターンの 1つでもあります。以下は、Google のパターンの例です。

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Args:
    parameter1: this is the first parameter.
    parameter2: this is the second parameter.

Returns:
    this is a description of what is returned by the function.

Raises:
    KeyError: raises an exception.
    TypeError: raises an exception.
"""

前のパターンと同様に、メソッドの簡潔な説明が一番上にあります。

説明の後には、Args、Returns、Raises などの見出しが続きます。Args 見出しの下に、タイプやデフォルト値などのすべてのパラメーターと詳細が配置されます。

関数によって返されるものの説明は、Returns 見出しの下に配置されます。最後に、エラーまたは例外とその詳細は、Raises の見出しの下に書き込まれます。

Numpydoc パターン

numpy モジュールには、Numpydoc パターンと呼ばれる docstring パターンがあります。

このパターンは Google のパターンに似ており、Sphinx ツールによって認識されます。Google のパターンと同様に、情報は見出しの下に整理されています。

以下は、Numpydoc パターンの例です。

"""
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.

Parameters
----------
parameter1 : int
    this is the first parameter.
parameter2 : str, "default value"
    this is the second parameter.

Returns
-------
string
    returns a string value.

Raises
------
KeyError
    raises an exception.
TypeError
    raises an exception.
"""

メソッドの説明は上部に書かれています。メソッドに関するその他の詳細は、Parameters、Returns、および Raises という見出しの下にまとめられています。

デフォルト値、値タイプなどを含むパラメータに関するすべての詳細は、Parameters 見出しの下に配置されます。データ型を含む、関数によって返されるものに関するすべての詳細は、Returns 見出しの下にあります。

最後に、エラーまたは例外に関する情報といくつかの説明は、Raises の見出しの下に書かれています。