🐍pythonotes

ドキュメンテーションは、コードの理解と保守を容易にする重要な要素です。適切なドキュメンテーションを提供することで、他の開発者がコードを理解しやすくなり、バグの発見や修正も効率的に行えます。この章では、Pythonコードのドキュメンテーションの書き方について説明します。

docstringは、Pythonの関数やクラスの冒頭に記載される、その機能や使い方を説明するためのコメントです。docstringは、三重引用符（"""）で囲まれたブロックとして記述します。

以下に、docstringの基本的な書き方の例を示します。

def add(a, b):
"""
二つの数値を受け取り、その和を返す関数。
Args:
    a (int): 加算する最初の数値。
    b (int): 加算する二番目の数値。

Returns:
    int: 二つの数値の和。
"""
return a + b

docstringには以下の要素を含めることが一般的です。

• 関数やクラスの目的や機能の概要
• 引数の説明（型、意味、デフォルト値など）
• 戻り値の説明（型、意味）
• 例外が発生する場合、その条件と例外の種類
• 使用例（オプション）

関数やクラスの内部にもコメントを書くことで、コードの理解を助けます。コメントは、コードの意図や目的を明確にし、複雑な処理や意図が不明な箇所に対する説明を提供することが目的です。

コメントは、#記号で始まり、その後に説明を記述します。コメントは、コードと同じインデントレベルにするか、新しい行で書くことが一般的です。

def factorial(n):
    # 入力値が0または1の場合、1を返す
    if n == 0 or n == 1:
        return 1

    # n * (n-1) * ... * 1 の計算を実行し、結果を返す
    result = 1
    for i in range(1, n + 1):
        result *= i
    return result

ドキュメンテーションとコメントを書く際のヒントを以下に示します。

1. シンプルで明確な言葉を使う 技術名や専門用語は避けるか、初めて利用する場合に説明を加えるようにしてください。
2. コメントはコードの補足 コメントはコード自体で説明できない部分を補足するものです。冗長なコメントは避け、必要最低限の情報を提供するように心がけましょう。
3. 更新時にコメントも更新 コードを変更する際は、コメントも適切に更新することが重要です。古いコメントは混乱を招くため、常に最新の状態に保ちましょう。