Pythonで関数のドキュメントを書く（docstring）

この記事では、Pythonにおける関数のdocstringの書き方、役割、そしてベストプラクティスについて説明します。効果的なdocstringの作成を通して、コードの可読性と保守性を向上させる方法を学びます。

docstringとは？

docstringは、関数、クラス、モジュールなどのコード要素の説明を記述するための文字列リテラルです。Pythonインタープリタはdocstringを特別なメタデータとして扱い、`help()`関数や`__doc__`属性を通してアクセスできます。docstringはコードの可読性を高め、保守性を向上させるために非常に重要です。

def my_function(arg1, arg2):
  """この関数は2つの引数を足し合わせて返します。\n\nArgs:\n  arg1: 最初の数値。\n  arg2: 2番目の数値。\n\nReturns:\n  2つの引数の和。"""
  return arg1 + arg2

print(help(my_function))

上記の例では、`my_function`関数のdocstringに、関数の機能、引数、戻り値について説明しています。`help()`関数は、このdocstringを表示します。

docstringの書き方

docstringは三重引用符（"""..."""）で囲みます。最初の行は簡潔な要約を記述し、空行を空けてから詳細な説明を記述します。引数、戻り値、例外などの情報を明確に記述することが重要です。

def calculate_average(numbers):
  """与えられた数値リストの平均を計算します。\n\nArgs:\n  numbers: 数値のリスト。\n\nReturns:\n  数値リストの平均。\n  リストが空の場合は0を返します。\n\nRaises:\n  TypeError: 入力リストに数値以外の要素が含まれている場合。"""
  if not numbers:
    return 0
  if not all(isinstance(num, (int, float)) for num in numbers):
    raise TypeError('入力リストには数値のみを含めることができます。')
  return sum(numbers) / len(numbers)

この例では、関数の機能、引数、戻り値、例外処理について詳細に記述しています。

docstringのスタイルガイド

docstringの記述には、いくつかのスタイルガイドが推奨されています。NumPyスタイルガイドやGoogleスタイルガイドなどが有名です。これらのスタイルガイドに従うことで、docstringの一貫性と可読性を高めることができます。

最初の行は簡潔な要約にする
空行で要約と詳細を分ける
引数、戻り値、例外を明確に記述する
ReSTやGoogleスタイルガイドのフォーマットを使用する

docstringの例

様々な状況におけるdocstringの例を示します。

# 関数のdocstring
def add(x, y):
  """2つの数値を加算する"""
  return x + y

# クラスのdocstring
class MyClass:
  """これはMyClassクラスです"""
  pass

# モジュールのdocstring
"""これは私のモジュールです"""

それぞれのdocstringは、そのコード要素の機能を簡潔に説明しています。

docstringとコードドキュメント生成ツール

Sphinxなどのコードドキュメント生成ツールは、docstringから自動的にドキュメントを生成できます。これにより、コードのドキュメント作成を効率化し、高品質なドキュメントを作成できます。

PYTHON MEBY