業務で開発するにしろ、個人で開発するにしろクラスやメソッド、関数を作成した際にドキュメントを記述しておくのはとても重要です。
時間がなくてこんなの書いている暇がない場合もあるかもしれませんが、絶対に書いておいた方がいいです。なんなら部下とかスキルが未熟なメンバーなど手が余っている人がいれば、そちらに振ってしまってもいいと思います。
勉強になりますしね。
Contents
ドキュメント（docstring）の大切さ
自分自身、プロジェクトの初期段階でドキュメントをおろそかにしていた経験があります。その結果、他のメンバーがコードを理解できず、質問が頻発しました。
また後からコードを見直した際にも、当時の意図を思い出すのが難しく、メンテナンスに時間がかかることはあるあるといってもいいのではないでしょうか。（ぼくだけ？）
しかしドキュメントをしっかり記述するようにすれば、他のメンバーとスムーズに連携でき、プロジェクトの進行が円滑になるというのはあります。
チーム開発でなくても自分自身が後からコードを確認する際に迷うことがなくなります。
ほかのメンバーや未来の自分のためにも書いておいた方が結果的に作業効率を高め、品質を向上させる重要な要素です。
忙しいときこそ、ドキュメントの記述を怠らず、将来の自分や他の開発者のために良質なコードを提供することを心がけるべきだと考えます。
docstringとは？
Pythonのドキュメントには、PEP 257というPython Enhancement Proposalによって定義されたdocstringのガイドラインが存在します。
docstring（ドックストリング）は、Pythonのモジュール、クラス、関数、またはメソッドの直後に配置される文字列リテラルで、コードの説明や使用方法を提供するために使います。
docstringは三重の引用符 (""" または ''') で囲まれます。
クラスの例
class Multiplier:
"""
A simple multiplier class.
"""
def multiply(self, a, b):
"""
Multiplies two numbers.
:param a: First number.
:param b: Second number.
:return: The product of a and b.
:rtype: int or float
"""
return a * bモジュールの例
"""
This module provides a set of mathematical operations.
"""ドキュメント（docstring）の重要性とメリット
- コードの可読性向上
ドキュメントを記述することで、コードの目的や使用方法、パラメータの説明、戻り値の詳細などが明確になります。他の開発者がコードを理解しやすくなり、チームでの作業が円滑に進みます。 - メンテナンスの効率化
コードの変更や追加が必要な際に、ドキュメントがあると迅速かつ正確に対応できます。特に大規模なプロジェクトでは、ドキュメントがあることでメンテナンスのコストを大幅に削減できます。 - 再利用性の向上
明確なドキュメントは、コードの再利用を容易にします。他のプロジェクトで同じ関数やクラスを使いたいとき、ドキュメントがあれば使用方法が一目瞭然です。 - バグの減少
ドキュメントがしっかりしていると、関数やメソッドの期待される動作が明確になります。そのためバグの発生を抑えたり、早期に特定したりすることができます。 - コードレビューの効率化
ドキュメントが充実していると、コードレビューの際に開発者同士が理解を共有しやすくなります。コードレビューがスムーズに進み、品質向上にも繋がります。
ドキュメント（docstring）の記述方法
Pythonではドキュメント（docstring）の記述方法にいくつかのスタイルがあります。
大別すると3つのスタイルがあるかと思います。
reStructuredText形式
reStructuredText（略してreST）形式は、Sphinxがデフォルトでサポートしているスタイルです。
reSTはPEP 287で定義されたマークアップ言語で、Sphinxのデフォルト形式でもあります。
Sphinxについては後述しますが、Sphinxを使う場合でもreStructuredText形式以外でも問題ないです。
def divide(a, b):
"""
Divides two numbers.
:param a: The numerator.
:param b: The denominator.
:return: The quotient of a and b.
:rtype: int or float
:raises ZeroDivisionError: If b is zero.
"""
if b == 0:
raise ZeroDivisionError("Cannot divide by zero.")
return a / b- 引数の説明には
:paramキーワードを使用。 - 戻り値の説明には
:returnキーワードを使用。 - 例外には :raisesキーワードを使用。
- 戻り値の型情報には
:rtypeキーワードを使用。
Google形式
Google形式は、Googleのスタイルガイドに基づいており、可読性とわかりやすさを重視しています。
自分はGoogle形式で書くことがほとんどですね。
def divide(a, b):
"""
Divides two numbers.
Args:
a (int or float): The numerator.
b (int or float): The denominator.
Returns:
float: The quotient of a and b.
Raises:
ZeroDivisionError: If b is zero.
"""
if b == 0:
raise ZeroDivisionError("Cannot divide by zero.")
return a / b- 引数の説明には
Args:セクションを使用。 - 戻り値の説明には
Returns:セクションを使用。 - 例外の説明には
Raises:セクションを使用。 - 型情報の説明は”引数名 (型名)”や”型名: “のパターンがある。
NumPy形式
Numpy形式は、NumPyのスタイルガイドに基づいており、科学技術系のプロジェクトでよく使用されるスタイルになっています。
def divide(a, b):
"""
Divides two numbers.
Parameters
----------
a : int or float
The numerator.
b : int or float
The denominator.
Returns
-------
float
The quotient of a and b.
Raises
------
ZeroDivisionError
If b is zero.
"""
if b == 0:
raise ZeroDivisionError("Cannot divide by zero.")
return a / b- 引数の説明:
Parametersセクションを使用。 - 戻り値の説明:
Returnsセクションを使用。 - 例外の説明:
Raisesセクションを使用。 - 型情報: 引数や戻り値の型情報は引数名や戻り値名の隣に記述。
Sphinxの利用
Sphinx（スフィンクス）は、Pythonのドキュメント生成ツールの1つです。
さまざまなプログラミング言語やプロジェクトのドキュメント生成に使われているSphinxですが、もともとはPythonのドキュメントを生成するために開発されました。
Sphinxは、主に以下の場合に利用されます。
- コードのドキュメント生成:
Pythonのモジュール、関数、クラスなどのdocstringを元に、ドキュメントを自動生成します。 - プロジェクトのドキュメント:
プロジェクト全体のドキュメント（使用方法、APIリファレンス、チュートリアルなど）をまとめる際に利用されます。 - 異なるフォーマットでのドキュメント生成:
HTML、PDF、EPUBなど、さまざまなフォーマットでのドキュメント生成が可能です。 - 複雑なプロジェクトのドキュメント管理:
大規模なプロジェクトのドキュメントを構造的に整理・管理するのに役立ちます。
Sphinxの使い方
Sphinxのインストールはpip（Pythonのパッケージマネージャ）を使用します。
pip install sphinx新しいプロジェクトを作成するには、以下のコマンドを使用します。
設定が完了すると、プロジェクトディレクトリに必要なファイルとフォルダが生成されます。
sphinx-quickstartドキュメントの編集はプロジェクトディレクトリ内のsourceフォルダに、ドキュメントを記述します。
index.rstファイルがプロジェクトのメインドキュメントです。
その他のドキュメントファイルもsourceフォルダに追加できます。
ドキュメントを生成するには、以下のコマンドを実行します。htmlの部分をpdfやepubに変更して、任意のフォーマットを指定してドキュメントを生成することも可能です。
make htmlSphinxでの設定
Sphinxのdocstringのスタイルは、デフォルトではeStructuredText形式になっています。
Google形式やNumPy形式などを使っている場合は別途指定してあげる必要があります。
指定方法は設定ファイル（conf.py）を編集して行います。
# conf.py の例
extensions = ['sphinx.ext.napoleon']
napoleon_google_docstring = True # Google形式を使用する
napoleon_numpy_docstring = False # NumPy形式を使用しない詳しい使い方や情報を知るにはやはり公式を参考にしてみてください。
