はじめに
docstringについて忘れないための備忘録です。
docstringとは
関数やクラス、モジュール全体の説明を行うためのコメントのことです。
'''又は"""で囲まれた範囲に説明を記載します。
PEP 257（Python Enhancement Proposal 257）にdocstringの書き方に関するガイドラインが示されています。
help()関数でdocstringの内容を参照することができます。
書き方のスタイルについて
書き方に主に3つあります。
-
Googleスタイル
Googleが推奨するスタイルで、簡潔かつ視覚的に分かりやすいのが特徴。 -
Numpyスタイル
科学技術分野でよく使われるNumPyライブラリで採用されているスタイル。説明が詳細でデータ型の記述が明確。 -
reStructuredTextスタイル
Sphinxを使ってドキュメントを生成する際に適しているスタイルです。Pythonコミュニティで広く支持されている。
Googleスタイル
def example_function(param1, param2, flag=True):
"""
Googleスタイルのdocstringの書き方を説明する関数です。
この関数は、Googleスタイルのdocstringの各セクションの構造を示します。
引数、戻り値、例外、使用例などを記述します。
Args:
param1 (int): 最初の引数で、整数を指定してください。
param2 (str): 2番目の引数で、文字列を指定してください。
flag (bool, optional): オプションの引数で、デフォルトはTrueです。
Returns:
str: 入力された値を基にした説明文を返します。
Raises:
ValueError: param1が負の数の場合に発生します。
TypeError: param2が文字列ではない場合に発生します。
Examples:
>>> example_function(5, "Python")
'入力値は5とPythonです。'
>>> example_function(-1, "Test")
ValueError: param1は0以上である必要があります。
"""
if not isinstance(param1, int):
raise TypeError("param1は整数である必要があります。")
if not isinstance(param2, str):
raise TypeError("param2は文字列である必要があります。")
if param1 < 0:
raise ValueError("param1は0以上である必要があります。")
return f"入力値は{param1}と{param2}です。"
Numpyスタイル
def example_function(param1, param2, flag=True):
"""
Numpyスタイルのdocstringの書き方を説明する関数です。
この関数は、Numpyスタイルのdocstringの各セクションの構造を示します。
引数、戻り値、例外、使用例などを記述します。
Parameters
----------
param1 : int
最初の引数で、整数を指定してください。
param2 : str
2番目の引数で、文字列を指定してください。
flag : bool, optional
オプションの引数で、デフォルトはTrueです。
Returns
-------
str
入力された値を基にした説明文を返します。
Raises
------
ValueError
param1が負の数の場合に発生します。
TypeError
param2が文字列ではない場合に発生します。
Examples
--------
>>> example_function(5, "Python")
'入力値は5とPythonです。'
>>> example_function(-1, "Test")
Traceback (most recent call last):
...
ValueError: param1は0以上である必要があります。
"""
if not isinstance(param1, int):
raise TypeError("param1は整数である必要があります。")
if not isinstance(param2, str):
raise TypeError("param2は文字列である必要があります。")
if param1 < 0:
raise ValueError("param1は0以上である必要があります。")
return f"入力値は{param1}と{param2}です。"
reStructuredTextスタイル
def example_function(param1, param2, flag=True):
"""
Googleスタイルのdocstringの書き方を説明する関数です。
この関数は、Googleスタイルのdocstringの各セクションの構造を示します。
引数、戻り値、例外、使用例などを記述します。
:param param1: 最初の引数で、整数を指定してください。
:type param1: int
:param param2: 2番目の引数で、文字列を指定してください。
:type param2: str
:param flag: オプションの引数で、デフォルトはTrueです。
:type flag: bool, optional
:return: 入力された値を基にした説明文を返します。
:rtype: str
:raises ValueError: param1が負の数の場合に発生します。
:raises TypeError: param2が文字列ではない場合に発生します。
:Example:
>>> example_function(5, "Python")
'入力値は5とPythonです。'
>>> example_function(-1, "Test")
Traceback (most recent call last):
...
ValueError: param1は0以上である必要があります。
"""
if not isinstance(param1, int):
raise TypeError("param1は整数である必要があります。")
if not isinstance(param2, str):
raise TypeError("param2は文字列である必要があります。")
if param1 < 0:
raise ValueError("param1は0以上である必要があります。")
return f"入力値は{param1}と{param2}です。"
おわりに
クラスやモジュールについての書き方については今度かければと思います。