22時に寝ようと思って2時に寝る。

備忘録や日記を書いてます。きょうは早く寝よう。

Pythonのドキュメンテーション文字列の書き方

ドキュメンテーション文字列 is 何

関数やモジュール、オブジェクトを書いて数日経つとどういった処理をしているのかを覚えていない…なんてことがあるので、Pythonでは"説明を最初の行に書いておきましょう!"という感じです。これはどのプログラミング言語でもだいたい共通しています。

最初の行は、常に対象物の目的を短く簡潔にまとめたものでなくてはなりません。簡潔に書くために、対象物の名前や型を明示する必要はありません。名前や型は他の方法でも得られるからです (名前がたまたま関数の演算内容を記述する動詞である場合は例外です)。最初の行は大文字で始まり、ピリオドで終わっていなければなりません。ドキュメンテーション文字列中にさらに記述すべき行がある場合、二行目は空行にし、まとめの行と残りの記述部分を視覚的に分離します。つづく行は一つまたはそれ以上の段落で、対象物の呼び出し規約や副作用について記述します。
4. その他の制御フローツール — Python 2.7ja1 documentation

なるほど。まとめると、

  • 最初の行に目的を完結に記述して
    • 対象物の名前や型は書かなくていいよ
    • 最初の行は大文字,最後はピリオドで締めて(英語で書くのなら)
  • 長くなりそうだったら二行目は空白にして3行目から詳しい続きを書いて
  • 詳しい内容ってのは対象物の呼び出し規則だったり副作用について書くといいよ

ざっくりとこんな感じかな。

例として関数についての記事(Python - 関数を作ってみる - ざっくりん雑記)で書いた"FizzBuzz"関数を含んだモジュールを作ってドキュメンテーション文字列を記述してみる。

# --- coding: utf-8 ---
u"FizzBuzzしてくれるモジュール."

def do_fizzbuzz(max=10):
    u""" 任意の数値で呼び出すと,その数値までFizzBuzzします.
   デフォルト引数は10に設定しているので,何も指定しないと10までFizzBuzzします.
  """
    for i in range(1,(max+1)):
        if i % 3 == 0 and i % 5 == 0:
            print 'FizzBuzz'
        elif i % 3 == 0:
            print 'Fizz'
        elif i % 5 == 0:
            print 'Buzz'
        else:
            print i
  • doctest.py を作っていじってみる
# --- coding: utf-8 ---

import fizzbuzz

help(fizzbuzz)

fizzbuzzモジュールをimportして、ドキュメントをhelp()で呼び出しみる。

help() については

組み込みヘルプシステムを起動します (この関数は対話的な使用のためのものです)。引数が与えられていない場合、対話的ヘルプシステムはインタプリタコンソール上で起動します。引数が文字列の場合、文字列はモジュール、関数、クラス、メソッド、キーワード、またはドキュメントの項目名として検索され、ヘルプページがコンソール上に印字されます。引数が何らかのオブジェクトの場合、そのオブジェクトに関するヘルプページが生成されます。
2. 組み込み関数 — Python 2.7ja1 documentation

今回は引数にモジュール名を入れているのでモジュールに設定されたヘルプページがコンソール上に印字されるはず。

  • 結果
Help on module fizzbuzz:

NAME
    fizzbuzz - FizzBuzzしてくれるモジュール.

FILE
    c:\users\hoge\fizzbuzz.py

FUNCTIONS
    do_fizzbuzz(max=10)
        任意の数値で呼び出すと,その数値までFizzBuzzします.
        デフォルト引数は10に設定しているので,何も指定しないと10までFizzBuzzします.

無事、記述したドキュメンテーション文字列がヘルプページの形式にフォーマットされて印字された。

まとめ

自分が書いた関数、モジュールであっても数日後見直すと何を書いているのか分からなくなる。未来への自分(共有したとするとあらゆる人に対して)へのメモ書きを"ドキュメンテーション文字列"で形式に則って書いておくことで help() で瞬時に呼び出せるってのが便利。

参考

Python で関数の説明を書く - ドキュメンテーション文字列 | すぐに忘れる脳みそのためのメモ

Python pydocの使い方、書き方とhtml出力の方法 - Symfoware

とりあえず: [Python][お勉強] Python入門(23) - ドキュメンテーション文字列