Python超入門その３３〜ドキュメントを書いてみよう〜

はじめに

コメントはしっかり書いていますか？

プログラムは書いている時間よりも、読んでいる時間のほうが長くなります。
これは一般に開発期間よりも、保守・運用期間のほうが長くなるためです。

このため、しっかりコメントを残して、他の人（一ヶ月後の自分も含む）のためにプログラムを解読する手がかりを残しておきましょう。通常のコメントだけでなく、ドキュメントコメントも合わせて書いておくと効果的です。

この記事では、Python初心者の方向けに、ドキュメントコメントの書き方や閲覧方法、pydocによるHTML化についてお伝えしていきます。
しっかりコメントを書いて、わかりやすいプログラムにしましょう。

通常のコメントのおさらい

まずは、通常のコメントのおさらいをしておきましょう。

コメントは、次のように「#」を使って書くのでした。

例：

 

コメントは行のどこからでも始めることができ、#から行末までがすべてコメントとして扱われます。
また、プログラムの説明だけでなく、プログラムの一部を一時的に無効化するためにも使われます。
これを「コメントアウト」といいます。

それでは、次にドキュメントコメントの書き方を学びましょう。

ドキュメントコメントを書いてみよう

ドキュメントコメントとは、通常のコメントとは違い、クラスやメソッドなどのドキュメント（説明文）として扱われる特別なコメントのことです。

Pythonでは、所定の位置に規定の方法で記述することでドキュメントコメントとして扱われます。

たとえば、次のようにします。

例：

 

この例のように、クラスやメソッド定義などの次の行に、単一行の場合は「”（または’）」、複数行の場合は「”””（または”’）」を使って記述します。

単なる説明文だけでなく、メソッドなどの使用例も実行結果と合わせて記述しておくと、よりわかりやすいドキュメントになるでしょう。

次は、このコメントを閲覧する方法についてみていきましょう。

ドキュメントコメントを閲覧する

ドキュメントコメントは、自動的に対象の”__doc__属性”に文字列として格納されます。
このため、次のように属性を介してアクセスすることができます。

例：

 

先程書いたコメントがそのまま出力されましたね。とはいえ、これだとあまり見やすいとはいえません。
そこで、もうひとつの方法として「help関数」を使ってみます。

次のコードを実行してみましょう。

例：

 

クラスとメソッドのドキュメントが一覧で表示されましたね。
これらの方法は、自分で書いたコードだけでなく、標準ライブラリなどにも使えます。

例：

 

ライブラリの使い方をサクッと調べたいときに、コンソールからPythonインタプリタを起動してhelp関数を使ってみるとよいでしょう。

pydocでドキュメントコメントをHTML化する

Pythonでは、pydocというツールが提供されており、ドキュメントコメントをHTML化してブラウザで閲覧したり、ファイルとして出力したりできます。
カラーリングなど見やすくする工夫がされているので、コンソールで見るよりも読みやすいでしょう。

また、いちいちPythonインタプリタを起動してhelp関数を実行しなくても、pydocでも同じドキュメントコメントが閲覧できます。

クイックリファレンスとして活用してみましょう。

まとめ

わかりやすいコメントが書けましたか？

単なる説明文だけでなく、関数やメソッドの使い方や実行結果などもドキュメントとして残しておくとよいでしょう。
ドキュメントコメントはコンソールから閲覧できる他、pydocによりHTML化してブラウザで閲覧することもできます。

ライブラリではAPIリファレンスのように使えるでしょう。

投稿者：プログラミング教育ナビ編集部

• tweet