Python、クラスや関数へのコメントの書き方


Pythonに限らず、ソースコードにコメントを書くことはよく行われます。
特に、モジュールやクラス、関数等へのコメントは
・どんな処理をするのか
・どんな引数を取るのか
・どんな値を返すのか
といったことがソースコードを読み解かなくてもわかるようになる為、できるだけ書くように推奨されています。

仕事では勿論ですが、趣味等であってもこれらのコメントを書く癖をつけることで、保守や拡張がしやすくなります。
理想としては、中身の処理を見なくても何をしているのかが把握でき、かつ、外部からそれらの関数やクラスを利用できることが目標です。

Pythonでは、ある決まった書き方をしたコメントは「ドキュメンテーション文字列」「ドックストリング」等と呼ばれ、特別に扱われます。
例えばですが…

mydoc.py

このようなモジュールやクラス・関数のすぐ下で、文字を「”””」で囲むことでドックストリングとして扱われます。
このドックストリングは、プログラム中から参照することが可能で、
今回の例では、以下のように参照ができます。

インタラクティブシェルにて、クラスや関数の動きを試したり、テストする際にこのhelp関数はよく使用します。

内部的な話をすると、このソースコード上に書いたコメントは
オブジェクトの__doc__という属性に格納されます。例えばですが、

とすると、

と表示されます。これはIDEやエディタの機能ではなく、Python自体の機能となっています。

この機能を利用し、Sphinx等のドキュメントビルドツールではにはAPIドキュメントの自動生成などを行っています。
ドックストリングを綺麗に書いていればそれだけでAPIドキュメントが作成できてしまうので、是非書く癖をつけましょう。

ドックストリングには、大まかな書き方のルールがあり、PEP257で定義されています。
その中から、大雑把に内容を説明します。
全体的な指針としては、シンプルで簡潔に書かれたものが好ましいです。

モジュール
モジュールドックストリングは、モジュールの内容を紹介するもので、重要なクラスや関数を見つけるための出発点になります。
1行目にはモジュールの目的を書き、それ以降に知っておくべき詳細や、メインとなるクラス、関数について紹介していきます。

クラス
1行目には、クラスの目的を記述します。それ以降には、重要なメソッドなどを紹介していき、
そのクラスをサブクラス化する上での注意点や、子クラスからアクセスして欲しくない属性などについても触れましょう。

関数
1行目には、関数が何をするか、について簡潔に書き、それ以降に振る舞いや引数、戻り値について書きます。

引数を持たず、単純な値を返す場合は、1行で簡潔に書きます。
先ほどのget_todayメソッドであれば、
「現在の日付を返す」
で充分でしょう。

戻り値を特に返さないならば、戻り値については触れないでおきましょう。
return なし
のようには、基本的には書きません。

シンプルすぎるのは勿論ですが、冗長な説明も好まれないため、綺麗なコメントを書くの中々大変です。
初めは、とりあえず全て1行程度で簡潔に書いておき、ちょっと説明が足りないな、と思ったら付け足していくぐらいでも良いでしょう。


関連記事一覧

コメント

  • コメント (0)

  • トラックバックは利用できません。

  1. この記事へのコメントはありません。

we love develop
アプリやシステムの開発を通じて、お客様のビジネスを成長させることが私たちのビジネスです。お気軽にお問い合わせください。
 お問い合せ

お電話でのお問い合わせはこちらから
TEL:03-5297-2871

メールマガジンの登録

キャパでは誰かに話したくなるようなIT小ネタを、週に一回メルマガで配信しています。
ぜひ購読してみませんか?
 購読する

ホワイトペーパーの入手

ITブログ月間20万PV達成!自社オウンドメディアの運用ノウハウを無料公開しています。
 ダウンロード

記事カテゴリ記事カテゴリ

月別投稿記事

PAGE TOP