Python で関数の説明を書く - ドキュメンテーション文字列

翌日になれば、昨日書いたメソッドの内容なんて忘れてしまう。 ^^; わかっているからいいやと思ってコメントを書くのを面倒くさがっていると、いつの間にかコードの森で迷子に…。 パタッ(o_ _)ｏ~†

Python でも、関数の説明を書くための書式に慣習があるようだ。「ドキュメンテーション文字列」と言うそうだが、最初見たときに違和感を感じた。関数の定義の前にその関数の説明を書くのではなく、関数の中の冒頭にコメントとして書く。他の言語では定義の前に書くことが多いので、これも Python 的と言えばそうなのだろうか。 (@_@)

 

書き方

4. その他の制御フローツール の「4.7.6 ドキュメンテーション文字列」から要点のみを抽出すると、

• 最初の行は、常に対象物の目的を短く簡潔にまとめたもの
  • 対象物の名前や型を明示する必要はありません。
  • 最初の行は大文字で始まり、ピリオドで終わっていなければなりません。
• 二行目は空行
• 最初の行の 後にある 空行でない最初の行が、ドキュメント全体のインデントの量を決めます。

Pythonを始めよう：CodeZine には、関数だけではなくモジュールの説明の書き方の例が記述されていた。とは言っても、何か特別なことをするわけではなく、関数と同じようにモジュールの先頭にコメントを書くだけのようだ。

 

例

では、試しに「身長と体重から求めるいくつかの指標を定義」したモジュールがあるとして、これにドキュメンテーション文字列を加えてみる。 heightAndWeight.py というファイルを作成し次のように記述した。

u""" 身長と体重から求めるいくつかの指標を定義。
"""

def bmi(weight, height):
    u""" 体重と身長から肥満度を判定するための BMI 指標を計算する

    体重(kg) / 身長(m)2 によって求められる。
    """
    return weight / height ** 2

これ以降にいくつかの関数が定義されると仮定してのもの。

コメントの前に `u’ を付けてユニコードであることを示しているのは、以下の操作で文字化けてしまったため。 (cf. Python で簡単なテキスト処理) しかし、上記のサイトの例では `u’ なんて付いてないし、どうすればいいんだろう… (@_@;)

同ファイルにおいて次のように続けた。

if __name__ == '__main__':
    print bmi.__doc__
    print help(__name__)

 

__doc__

上記を実行すると、まず __doc__  の呼出しにより、

 体重と身長から肥満度を判定するための BMI 指標を計算する

    体重(kg) / 身長(m)2 によって求められる。

というように、関数の冒頭に書いたコメントによる関数の説明が表示される。__doc__ については 3.11.1 型とメンバ を参照。

 

help()

次に help() によって、今度はモジュール全体の情報が表示される。

Help on built-in module __main__:

NAME
    __main__ - 身長と体重から求めるいくつかの指標を定義。

FILE
    (built-in)

FUNCTIONS
    bmi(weight, height)
        体重と身長から肥満度を判定するための BMI 指標を計算する
        
        体重(kg) / 身長(m)2 によって求められる。


None

2.1 組み込み関数 によると、

help([object])

組み込みヘルプシステムを起動します (この関数は対話的な使用のためのものです)。(…)

引数が文字列の場合、文字列はモジュール、関数、クラス、メソッド、キーワード、またはドキュメントの項目名として検索され、ヘルプページがコンソール上に印字されます。引数が何らかのオブジェクトの場合、そのオブジェクトに関するヘルプページが生成されます。 バージョン 2.2 で 新たに追加 された仕様です。

「対話的な使用のためのもの」とあるので、普通はファイルに記述して実行のようなことはしないのだろうか…。 上記の結果において、FILE の項目を見ると、(built-in) となっている。なぜだろう？次のように、別のモジュールから help() を呼びだしてみる。

test.py というファイルを作成。

import heightAndWeight
help(heightAndWeight)

これを実行すると、

Help on module heightAndWeight:

NAME
    heightAndWeight - 身長と体重から求めるいくつかの指標を定義。

FILE
    c:\develop\src\python\heightandweight.py

FUNCTIONS
    bmi(weight, height)
        体重と身長から肥満度を判定するための BMI 指標を計算する
        
        体重(kg) / 身長(m)2 によって求められる。

モジュールの名前とファイル名が表示された。考えてみれば、先ほどのコードでは help(__name__) としており、そのファイルをスクリプトの実行の起点としているので、 __name__ は メインモジュールの名前、つまり __main__ となり、bmi 関数はそこに所属するということになるのだろう。多分。 ^^;

 

参考

• UchのX40記: [Python]関数(ドキュメンテーション文字列編)

上記の指標の内容については、

• BMI判定
• 一歩一歩学ぶ医学生理学