本記事について
docstringにはSphinxの(公式ページ
)に記載があるようにGoogle StyleとNumPy Styleがありますが、ここではGoogle Styleのdocstringについて記載します。
詳細なGoogle Styleについて以下を参照ください。
なお、NumPy Styleについては素晴らしい記事があったため、参考リンクに記載しました。
docstringサンプルコード例
docstring例を以下に記載します。
"""
電卓クラスモジュール
本モジュールは、四則演算を行うシンプルな電卓クラスを提供します。
電卓クラスは、最後に計算した結果を保持し、メモを保存する機能も持っています。
To Do:
- サポートする数学的操作を増やす（例：べき乗、平方根など）
- ログ機能の追加（例：全ての計算履歴を保持する）
"""
class SimpleCalculator:
"""
四則演算を行うシンプルな電卓クラス。
Attributes:
last_result (float): 最後に計算した結果
memo (str): メモの内容
Note:
メモには計算内容を記載すること
"""
def __init__(self, memo: str = ""):
"""
初期化メソッド
Args:
memo (str): メモの内容。デフォルトは空文字
"""
self.last_result = 0.0
self.memo = memo
def add(self, a: float, b: float) -> float:
"""
足し算を行うメソッド
Args:
a (float): 一つ目の数値
b (float): 二つ目の数値
Returns:
float: 計算結果。
"""
self.last_result = a + b
return self.last_result
def subtract(self, a: float, b: float) -> float:
"""
引き算を行うメソッド。
Args:
a (float): 一つ目の数値。
b (float): 二つ目の数値。
Returns:
float: 計算結果。
"""
self.last_result = a - b
return self.last_result
def multiply(self, a: float, b: float) -> float:
"""
掛け算を行うメソッド
Args:
a (float): 一つ目の数値
b (float): 二つ目の数値
Returns:
float: 計算結果
"""
self.last_result = a * b
return self.last_result
def divide(self, a: float, b: float) -> float:
"""
割り算を行うメソッド。ゼロ除算をチェックします
Args:
a (float): 一つ目の数値
b (float): 二つ目の数値
Returns:
float: 計算結果
Raises:
ValueError: b がゼロの場合
"""
if b == 0:
raise ValueError("ゼロで割ることはできません。")
self.last_result = a / b
return self.last_result
モジュール(xxx.py)説明のためのdocstring
まず、モジュールの説明をファイルの先頭に記載します。
"""
電卓クラスモジュール
本モジュールは、四則演算を行うシンプルな電卓クラスを提供します。
電卓クラスは、最後に計算した結果を保持し、メモを保存する機能も持っています。
"""
To DO セクション
モジュールの説明の後に記載します。To Doセクションでは、将来的に追加したい機能や改善点を箇条書きで記載します。
"""
To Do:
- サポートする数学的操作を増やす（例：べき乗、平方根など）
- ログ機能の追加（例：全ての計算履歴を保持する）
"""
Attributesセクション
クラスのインスタンス変数(例ではself.last_resultやself.memo)を記載します。
Attributes:
インスタンス変数1 (変数1の型): 変数1の説明
インスタンス変数2 (変数2の型): 変数2の説明
Argsセクション
関数の引数について記載します。
Args:
引数1 (引数1の型): 引数1の説明
引数2 (引数2の型): 引数2の説明
Returnsセクション
関数の戻り値について記載します。
Returns:
戻り値の型: 戻り値の説明
Raisesセクション
例外処理に対する説明を記載します。
Raises:
ValueError: b がゼロの場合
Notesセクション
注意事項などを記載します。
Note:
メモには計算内容を記載すること