初めてのPython(14章)
Pythonのドキュメントについて
ドキュメントの種類と表示方法
ドキュメントは、コードの内容と一致させるように努める。
| 種類 | 内容 |
|---|---|
| #を使ったコメント | プログラムの中に組み込む |
| docstring(__doc__) | プログラムの中に組み込む、help関数などで中身を見れる |
| 標準マニュアルセット | Python言語やツールセットに関する標準マニュアル |
| Webサイト | オンラインチュートリアル、リファレンスなど |
| 書籍 | 市販書籍 |
| 方法 | 表示内容 |
|---|---|
| dir関数 | オブジェクトの属性のリストを表示する |
| help関数 | テキストベースでドキュメントを表示する |
#を使ったコメント
後述のdocstringとは違い、ソースコードを開かないと内容を参照できない。
書き方
書き方に関する決まりがPEP8に。
PEPは、Python Enhancement Proposalsの略。
PEP8はPythonプログラムの書き方についての決まりを述べたもの。
#のコメントだけでなく、docstringについても言及されている
#を使ったコメントの書き方は
- 1行コメントの場合
- #の後ろにスペースを一つあけてコメントを始める
- 『コメントは文章』が基本で、ピリオド(.)で終わる。
- ピリオドの後は２つスペースを空けておく
- ブロックコメントの場合
- 次に続くコードをインデントを合わせる(コメントの内容が次に続くコードのことだから)
- １行コメント同様に、# で始まり、スペースを1つあけてコメントを書く
- ブロックコメント内でパラグラフを変える時は、空の#行を挟む
- インラインコメントは使わない方が良い
docstring
プログラム実行時に、インタプリタによって__doc__オブジェクトに対応づけられる。
help関数などを使うことで、ソースコードを開かなくても内容を参照できる。
docstringを置く場所は、
- モジュールファイルの先頭
- クラス/関数のコードの先頭(実行可能コードは、docstringの後に置く)
書き方
置く場所さえ従っていれば、シングルクォートでもトリプルクォートでもdocstringとして扱われる。
ただ、複数行にまたがって書くことが多いため、トリプルクォートを使うのが一般的。
- 1行docstringの場合
- 終わりの"""は改行しない
- 前後に空白行を入れない
- ピリオド(.)で終わる句(主語無し)で、コマンドとして機能やメソッドの効果を記述する
- 使い方とかパラメータのことは書かない。
- 複数行docstringの場合
- 終わりの"""は改行して、それだけの行にする
- 1行docstring(サマリーとして機能)、改行、詳細な記述から構成する
- 前後に空白行を入れる
