ドキュメンテーション文字列（docstring）

ドキュメンテーション文字列（docstring）は、Pythonの関数、クラス、モジュールの目的や使用方法を説明するために使われる文字列です。これにより、コードの可読性が向上し、他の開発者があなたのコードの意図を理解しやすくなります。

docstringの基本

ドキュメンテーション文字列は、関数の定義の直後に三重引用符（''' または """）で囲まれた文字列として記述します。以下は、docstringの基本的な構文です。

def 関数名(引数):
    """
    関数の説明

    引数:
    引数名 (型): 引数に関する説明

    戻り値:
    戻り値の型: 戻り値に関する説明
    """
    # 関数の処理
    return 戻り値

サンプルコード

それでは、具体的な例を見てみましょう。

def add(a, b):
    """
    2つの数を加算します。

    引数:
    a (int or float): 加算する最初の数
    b (int or float): 加算する2番目の数

    戻り値:
    int or float: aとbの合計
    """
    return a + b

コードの解説

1. 関数の定義: def add(a, b): で関数addを定義しています。この関数は2つの引数aとbを受け取ります。

2. docstring: 関数の直後に三重引用符で囲まれた文字列があり、これがdocstringです。関数の目的、引数、戻り値についての説明が含まれています。

3. 戻り値: return a + b で、引数の合計を計算し、その結果を返します。

docstringの確認

Pythonでは、関数のdocstringにアクセスするために、__doc__属性を使用します。次のようにして確認できます。

print(add.__doc__)

このコードを実行すると、add関数のdocstringが表示されます。

組み込み関数との比較

Pythonの組み込み関数やライブラリでもdocstringが重要です。例えば、len()関数のdocstringを確認してみましょう。

print(len.__doc__)

これにより、len関数がどのように機能するかについての説明が得られます。

まとめ

ドキュメンテーション文字列は、コードの品質を向上させるために非常に重要です。良いdocstringを書くことで、他の開発者や将来の自分がコードを理解しやすくなります。以下は、良いdocstringを書くためのポイントです。

• 関数の目的を明確にする
• 引数と戻り値の型と説明を記載する
• 可能であれば、使用例を追加する

docstringを活用して、あなたのコードの可読性を向上させましょう。