Python では関数に doc string と言われる文字列を与えることで, 説明を付けることができます.
Example 2.2. buildConnectionString 関数の doc string の定義
def buildConnectionString(params): """Build a connection string from a dictionary of parameters. Returns string."""
3 つの連続した引用符は複数行に渡る文字列を表しています. 引用符の開始から終わりまでは, 改行や他の引用符も含めて全て 1 つの文字列の一部となります. これはプログラムのどこでも使えますが, これが使われているのを一番良く目にするのは doc string の定義でしょう.
 |
|
| また Perl の qq/.../ のように, 3 連引用符は単引用符や二重引用符を含んだ文字列を定義する簡単な方法です. | |
2 つの 3 連引用符の間にあるものは全て, 関数の振舞いを説明する doc string になります. doc string は, もしあるならば, 関数内で最初に定義されていなければなりません. (つまり, コロンのすぐ後ということです.) あなたが定義した関数に doc string を付ける必要は技術的な意味では無いのですが, やはり常に付けるべきです. このことは今まで受けたどのプログラミングの授業でも聞いたことがあるとは思いますが, Python にはそのようにする更なる動機があります. doc string は実行時に, 関数の属性として利用可能なのです.
|
|
| 多くの Python IDE は doc string を文脈を読むのに役立つ文書として提供するのに使用していて, 関数名を打ったときにその doc string が簡単な使い方の説明として表れます. この機能はとても助かるのですが, それはもちろん doc string をきちんと書いた分だけです. | |
文書化機能についてさらに知るには
- PEP 257 では, doc string の慣習が定義されています.
- Python Style Guide では, 良い doc string はどう書けば良いのかについて議論しています.
- Python Tutorial では doc string の空白の取り方の慣習について議論しています.