Docstring とは
Pythonにおいて、Docstringとは、モジュール、関数、クラス、またはメソッドの定義の最初の文として現れる文字列リテラルのことを指します。Docstringの目的は、その後に続くコードの目的、振る舞い、使用法についての文書化することです。Docstringは、単一行または複数行の文字列であり、シングルクオートまたはダブルクオートを使用して記述します。
Docstring の重要性
以下は、PythonにおいてDocstringが重要な理由です。
-
明確さと可読性
Docstringは、コードが何を行い、どのように使用するかを明確に説明することで、コードをより読みやすく理解しやすくするのに役立ちます。開発者はDocstringを読むことで、関数、クラス、またはモジュールの目的や、自分のコードでどのように使用するかをすばやく理解することができます。 -
ドキュメンテーション
Docstringは、コードをドキュメントするための方法として機能し、他の開発者がコードの動作方法や使用方法を理解しやすくします。これは特に大規模なプロジェクトで複数の開発者が同じコードベースで作業している場合に重要です。 -
メンテナンスとリファクタリング
Docstringは、コードをメンテナンスおよびリファクタリングする際に役立ちます。コードが何を行っているかの参照を提供するため、変更が必要な箇所を特定し、どのように変更するかを簡単に特定することができます。 -
テストおよびデバッグ
Docstringは、コードのテストとデバッグに使用することができます。コードがどのように動作するかを明確に説明することで、開発者はコードが期待どおりに動作していることを確認することができます。
Docstring スタイル
Pythonでは、複数のDocstringのスタイルがあります。使用する書式は、Python標準ライブラリやサードパーティのスタイルガイドで定められたガイドラインに従う必要があるかどうか、個人の好みによって異なります。以下は、Pythonでもっとも一般的なDocstringスタイルです。
reStructuredText (reST)
reStructuredText (reST) は、Pythonをはじめとする他のプログラミング言語でドキュメントを作成するために使用される軽量のマークアップ言語です。読みやすく書きやすく、柔軟で拡張性のあるドキュメント作成フォーマットを提供するように設計されています。
以下は、reSTスタイルのPython Docstringの例です。
def my_function(arg1, arg2):
"""
Brief description of the function.
A longer description that goes into more detail about the function and how it works.
:param arg1: Description of arg1.
:type arg1: int
:param arg2: Description of arg2.
:type arg2: str
:return: Description of the return value.
:rtype: bool
:raises ValueError: If the function encounters a value error.
"""
# function code goes here
この例では、Docstringは関数が何をするかの簡単な要約から始まり、詳細な説明が続きます。パラメータは:paramと:typeのディレクティブを使って文書化され、戻り値は:returnと:rtypeのディレクティブを使って文書化されます。：raisesディレクティブは、関数が発生させる可能性のある例外を文書化するために使用されます。
reSTフォーマットは非常に柔軟で拡張性があり、HTML、LaTeX、PDFを含む幅広いドキュメンテーションスタイルを作成するために使用できます。また、学習や使用も容易であるため、Python開発者の人気のある選択肢の一つです。
Google スタイル
Googleスタイルは、Googleや多くの他のオープンソースプロジェクトで使用されているDocstringの人気のあるフォーマットです。明確さと一貫性に焦点を当て、簡単で読みやすいように設計されています。
以下は、Googleスタイルで書かれたPythonのDocstringの例です。
def my_function(arg1, arg2):
"""
Brief description of the function.
A longer description that goes into more detail about the function and how it works.
Args:
arg1 (int): Description of arg1.
arg2 (str): Description of arg2.
Returns:
bool: Description of the return value.
Raises:
ValueError: If the function encounters a value error.
"""
# function code goes here
この例では、関数が何をするかの簡単な概要から始まり、その後により詳細な説明が続きます。Argsセクションには、各パラメータの説明とその型が含まれています。Returnsセクションには、関数が返す値とその型の説明が含まれています。Raisesセクションには、関数が発生させる可能性のある例外が含まれています。
Googleスタイルは、他の開発者があなたのコードを使用する際に読みやすく理解しやすく、比較的簡潔であるため、複雑な関数やライブラリを文書化する際に役立ちます。
NumPy スタイル
NumPyスタイルは、NumPyライブラリや多くの科学技術Pythonパッケージで使用されるDocstringスタイルです。NumPyドキュメントスタイルに準拠し、科学技術関数やライブラリを文書化するための明確で構造化された方法を提供するように設計されています。
NumPyスタイル形式のPython Docstringの例を示します。
def my_function(arg1, arg2):
"""
Brief description of the function.
Parameters
----------
arg1 : int
Description of arg1.
arg2 : str
Description of arg2.
Returns
-------
bool
Description of the return value.
Raises
------
ValueError
If the function encounters a value error.
"""
# function code goes here
この例では、Docstringは、関数が何を行うかを簡潔にまとめた説明から始まり、各パラメータの説明と型を含むParametersセクションが続きます。Returnsセクションは、関数が返すものとその型の説明を含みます。Raisesセクションは、関数が発生させる可能性のある例外を記述します。
NumPyスタイルは、科学的な機能やライブラリにとって特に有用であり、複雑なアルゴリズムや計算をドキュメント化するための一貫した方法を提供します。また、数学的な表記やフォーマットを使用することもできるため、科学的なコードのドキュメント化に役立ちます。
参考
Ryusei Kakujo
Focusing on data science for mobility
Bench Press 100kg!