Index
ドキュメントストリング
ドキュメントストリングの役割
ドキュメントストリングの役割として、次のようなものが挙げられます。
- オブジェクトの機能や使用方法を説明する
- 引数や戻り値の型や意味を説明する
- 例示や注意事項などを記述する
- 作者やバージョン情報などを記述する
ドキュメントストリングの書き方
モジュールの冒頭、クラスの冒頭、関数の先頭にトリプルクォート"""で囲んで記述します。
（例）
def solve_quadratic_equation(a, b, c): """ 二次方程式 ax^2 + bx + c = 0 を解きます。 Args: a: float, x^2 の係数 b: float, x の係数 c: float, 定数項 Returns: Tuple[float, float]: x1, x2 の解 """ if a == 0: if b == 0: return None else: return -c / b else: delta = b**2 - 4 * a * c if delta > 0: x1 = (-b + np.sqrt(delta)) / (2 * a) x2 = (-b - np.sqrt(delta)) / (2 * a) return x1, x2 elif delta == 0: return -b / (2 * a) else: return None
上記の例では二次方程式を解く関数を定義しています。この関数の先頭にあるトリプルクォート"""で囲んである部分がドキュメントストリングになります。
VSCodeの拡張機能を使ってドキュメントストリングを記述する
「autoDocstring - Python Docstring Generator」という拡張機能を使うと楽にドキュメントストリングを記述することができます。
File > Preferences > Settings（またはCtrl + ,）でSettingsを開き、docstringと検索すると Docstring Formatが選択できます。デフォルトでは googleになっていますが、他のフォーマットも選択できます。googleスタイルは他のフォーマットに比べて縦に長くならないので、googleスタイルで問題ないと思います。
トリプルクォート"""を入力すると、Generate Docstringと表示されます。これを選択すると自動でドキュメントストリングのテンプレートが記述されます。Ctrl+Shift+2でも可能です。
googleスタイルでは、summary部分には関数の概要を記述します。Args部分に引数名が自動で入力されるため、typeに引数の型、descriptionに引数の説明を記述します。Returnsには返り値の型と説明を入力します。
（再掲）
def solve_quadratic_equation(a, b, c): """ 二次方程式 ax^2 + bx + c = 0 を解きます。 Args: a: float, x^2 の係数 b: float, x の係数 c: float, 定数項 Returns: Tuple[float, float]: x1, x2 の解 """ if a == 0: if b == 0: return None else: return -c / b else: delta = b**2 - 4 * a * c if delta > 0: x1 = (-b + np.sqrt(delta)) / (2 * a) x2 = (-b - np.sqrt(delta)) / (2 * a) return x1, x2 elif delta == 0: return -b / (2 * a) else: return None
ドキュメントストリングを書いた部分にカーソルを合わせるとドキュメントストリングが表示され、そのモジュール、クラス、関数の説明を見ることができます。
サンプル
Geminiで生成したモジュール、クラス、関数のドキュメントストリングのサンプルを載せておきます。
""" モジュール： これはサンプルモジュールです。 このモジュールは、サンプル関数とサンプルクラスを提供します。 """ def sample_function(arg1, arg2): """ 関数： これはサンプル関数です。 引数： arg1: サンプル引数1 arg2: サンプル引数2 戻り値： arg1 と arg2 を加算した結果 """ return arg1 + arg2 class SampleClass: """ クラス： これはサンプルクラスです。 属性： attr1: サンプル属性1 attr2: サンプル属性2 メソッド： sample_method(): サンプルメソッド """ def __init__(self, attr1, attr2): self.attr1 = attr1 self.attr2 = attr2 def sample_method(self): """ メソッド： これはサンプルメソッドです。 このメソッドは、属性 attr1 と attr2 を返します。 戻り値： 属性 attr1 と attr2 のタプル """ return self.attr1, self.attr2
