はじめに
この実験（Lab）では、Python コードを docstring（ドキュメンテーション文字列）を使用して文書化することの重要性について学びます。組み込み関数（built-in functions）の既存の docstring にhelp()関数と__doc__属性を使用してアクセスする方法を探ります。
さらに、カスタム関数（custom functions）に対して独自の docstring を記述し、そのアクセス可能性を確認する実践的な経験を積み、あなた自身や他の人にとってコードの理解度と保守性を高めることができます。
help() を使用したドキュメントへのアクセス
docstring（ドキュメンテーション文字列）は、モジュール、関数、クラス、またはメソッド定義において最初のステートメントとして現れる文字列リテラルです。これはコードが何をするかを文書化するために使用されます。Python の組み込み関数であるhelp()関数は、このドキュメンテーションをクリーンで読みやすい形式で表示するための優れたツールです。help()関数は対話的な使用のために設計されています。
まず、組み込みのprint()関数のドキュメンテーションを表示することから始めましょう。
最初に、WebIDE でターミナルを開きます。これを行うには、画面上部のTerminalメニューをクリックし、New Terminalを選択します。
ターミナルで、次のコマンドを入力して Enter を押し、Python の対話型シェルを起動します。
python
Python プロンプト（>>>）が表示されます。次に、help()関数を使用してprint()に関する情報を取得します。
help(print)
ターミナルにprint関数のドキュメンテーションが表示されます。
Help on built-in function print in module builtins:
print(value, ..., sep=' ', end='\n', file=sys.stdout, flush=False)
Prints the values to a stream, or to sys.stdout by default.
Optional keyword arguments:
file: a file-like object (stream); defaults to the current sys.stdout.
sep: string inserted between values, default a space.
end: string appended after the last value, default a newline.
flush: whether to forcibly flush the stream.
(END)
この出力は、関数が何をするか、受け入れるパラメータ、およびそれらのデフォルト値について説明しています。ヘルプビューアを終了し、Python プロンプトに戻るには、qキーを押してください。
次に、次のコマンドを入力して Python 対話型シェルを終了します。
exit()
__doc__ を使用した生の docstring へのアクセス
help()は対話的な使用には優れていますが、オブジェクトの特別な属性である__doc__を使用して、プログラム的に生の docstring にアクセスすることもできます。この属性は docstring をプレーンな文字列として保持します。
これを実際に見てみましょう。WebIDE の左側にあるファイルエクスプローラーで、access_docstring.pyという名前のファイルを見つけて開きます。
ファイルに次の Python コードを追加します。このコードは、組み込みのlen()関数の docstring を出力します。
## This script prints the docstring of the len() function.
print(len.__doc__)
ファイルを保存します（ショートカットCtrl+Sを使用できます）。
次に、ターミナルに戻り、次のコマンドでスクリプトを実行します。
python access_docstring.py
出力は、len関数の生の docstring になります。
Return the number of items in a container.
ご覧のとおり、__doc__はドキュメンテーションの直接的な文字列コンテンツを提供します。これは、ドキュメンテーションを処理するカスタムツールやスクリプトにとって役立つ場合があります。
カスタム関数の Docstring の記述
独自の関数を文書化することは、クリーンで保守性の高いコードを書くための基本的な実践です。良い docstring は、関数の目的、パラメータ、および戻り値を説明するべきです。
関数を記述し、それを文書化してみましょう。ファイルエクスプローラーからmy_function.pyファイルを開きます。
まず、次の関数定義をファイルに追加します。
def greet(name, greeting="Hello"):
print(f"{greeting}, {name}!")
次に、docstring を追加します。docstring はdef行の直後に配置され、関数のコードと同じインデントレベルである必要があります。複数行の docstring には、トリプルクォート（"""..."""）を使用します。
docstring を含めるようにmy_function.pyを変更します。また、それが機能することを確認するために、docstring を出力する行を追加します。
def greet(name, greeting="Hello"):
"""Greets a person with a given message.
Args:
name (str): The name of the person to greet.
greeting (str, optional): The greeting message. Defaults to "Hello".
"""
print(f"{greeting}, {name}!")
## Print the docstring of our greet function
print(greet.__doc__)
ファイルを保存します。次に、ターミナルからスクリプトを実行します。
python my_function.py
カスタム docstring がコンソールに出力されているのが確認できます。
Greets a person with a given message.
Args:
name (str): The name of the person to greet.
greeting (str, optional): The greeting message. Defaults to "Hello".
これにより、関数を正常に文書化し、__doc__属性を使用してその docstring にアクセスできることが確認できました。
カスタム関数での help() の使用
前のステップでは、__doc__を使用してカスタム docstring にアクセスしました。今度は、組み込みのprint()関数で行ったのと同じように、help()関数を使用して、より洗練され、ユーザーフレンドリーな形式でドキュメントを表示してみましょう。
help()を使用するために、greet関数を Python の対話型シェルにインポートします。
ターミナルで、Python シェルを再度起動します。
python
>>>プロンプトが表示されたら、my_functionモジュール（ファイル名my_function.pyはmy_functionという名前のモジュールとして扱われます）からgreet関数をインポートします。
from my_function import greet
次に、help()を使用してgreet関数のドキュメントを表示します。
help(greet)
docstring から生成された、きれいにフォーマットされた出力が表示されます。
Help on function greet in module my_function:
greet(name, greeting='Hello')
Greets a person with a given message.
Args:
name (str): The name of the person to greet.
greeting (str, optional): The greeting message. Defaults to "Hello".
(END)
help()が関数のシグネチャ（greet(name, greeting='Hello')）を自動的に含め、docstring を読みやすいようにフォーマットする方法に注目してください。これが、良い docstring を書くことが非常に価値がある理由です。組み込みのヘルプシステムと直接統合されるからです。
qを押してヘルプビューアを終了し、次にexit()と入力して Python シェルを終了します。
まとめ
この実験（Lab）では、docstring を使用した Python コードの文書化の基本を学びました。対話型シェルでhelp()関数と__doc__属性を使用して、組み込み関数のドキュメントにアクセスする練習をしました。その後、標準的な慣習に従って、カスタム関数に対して独自の単一行および複数行の docstring を記述することで、この知識を適用しました。最後に、カスタムドキュメントが__doc__と Python のhelp()システムの両方からアクセス可能であることを確認しました。これは、読みやすく、再利用可能で、保守性の高いコードを作成するための重要なスキルです。
