naritoPythonに限らず、ソースコードにコメントを書くことはよく行われます。モジュールやクラス、関数等へのコメントは・どんな処理をするのか・どんな引数を取るのか・どんな値を返すのかといったことがソースコードを読み解かなくてもわかるようになる為、できるだけ書くように推奨されています。仕事では勿論ですが、趣味等であってもこれらのコメントを書く癖をつけることで、保守や拡張がしやすくなります。理想としては、中身の処理を見なくても何をしているのかが把握でき、かつ、外部からそれらの関数やクラスを利用できることが目標です。Pythonでは、ある決まった書き方をしたコメントは「ドキュメンテーション文字列」「ドックストリング」等と呼ばれ、特別に扱われます。何かしらの処理このようなモジュールやクラス・関数のすぐ下で、文字を「”””」で囲むことでドックストリングとして扱われます。今回の例では、以下のように参照ができます。現在の日付を返します......インタラクティブシェルにて、クラスや関数の動きを試したり、テストする際にこのhelp関数はよく使用します。内部的な話をすると、このソースコード上に書いたコメントはオブジェクトの__doc__という属性に格納されます。日付を便利に扱うクラスと表示されます。これはIDEやエディタの機能ではなく、Python自体の機能となっています。この機能を利用し、Sphinx等のドキュメントビルドツールではにはAPIドキュメントの自動生成などを行っています。ドックストリングを綺麗に書いていればそれだけでAPIドキュメントが作成できてしまうので、是非書く癖をつけましょう。ドックストリングには、大まかな書き方のルールがあり、PEP257で定義されています。その中から、大雑把に内容を説明します。全体的な指針としては、シンプルで簡潔に書かれたものが好ましいです。モジュールモジュールドックストリングは、モジュールの内容を紹介するもので、重要なクラスや関数を見つけるための出発点になります。1行目にはモジュールの目的を書き、それ以降に知っておくべき詳細や、メインとなるクラス、関数について紹介していきます。クラス1行目には、クラスの目的を記述します。それ以降には、重要なメソッドなどを紹介していき、そのクラスをサブクラス化する上での注意点や、子クラスからアクセスして欲しくない属性などについても触れましょう。関数1行目には、関数が何をするか、について簡潔に書き、それ以降に振る舞いや引数、戻り値について書きます。引数を持たず、単純な値を返す場合は、1行で簡潔に書きます。「現在の日付を返す」で充分でしょう。戻り値を特に返さないならば、戻り値については触れないでおきましょう。なしのようには、基本的には書きません。シンプルすぎるのは勿論ですが、冗長な説明も好まれないため、綺麗なコメントを書くの中々大変です。初めは、とりあえず全て1行程度で簡潔に書いておき、ちょっと説明が足りないな、と思ったら付け足していくぐらいでも良いでしょう。この記事を読んだ人は、こちらの記事も読んでいます。建設資材のコスト予測。