プログラミングは、コンピュータを使って問題を解決するための一つの手順を記述するために、自分の考え方が反映されます。
コードをコメントすることで、自分の思考過程を説明することができ、コードの意図を後から自分も他人も理解することができます。
これにより、より簡単にエラーを見つけ、それを修正し、後でコードを改善し、他のアプリケーションでも再利用することができます。
コメントは、小規模、中規模、大規模を問わず、あらゆる種類のプロジェクトで重要です。
ワークフローには欠かせないものであり、開発者にとってのグッドプラクティスとされています。
コメントなしでは、物事はすぐに混乱してしまいます。
この記事では、Pythonがサポートするさまざまなコメント付けの方法と、いわゆるモジュールレベルのdocstringを使用してコードのドキュメントを自動的に作成するためにそれをどのように使用できるかを説明します。
良いコメントと悪いコメントの比較
コメントは重要ですが、悪いコメントを書くこともあります。
コメントは常に短く、要点をついていて、有益な価値を与えるものでなければなりません。
例えば、これはかなり無駄なコメントです。
b = 56 # assigning b a value of 56
次の例は、もっと役に立つコメントで、変数にわかりやすい名前をつけることに沿っています。
salestax10 = 1.10 # defining a sales tax of 10%
salestax20 = 1.20 # defining a sales tax of 20%
このほかにも、コメントをつけるべき場面は無数にあります。
これはほんの一例です。
経験則から言うと、コードの行（リスト内包など）や目的が明らかでない部分にはコメントを付けるとよいでしょう。
これは非常に主観的なもので、実際には学ぶ必要のあるスキルです。
コメントの種類
Pythonのコメントは、ハッシュ文字 # で始まり、物理行の終わりまで続きます。
ただし、文字列の中にハッシュ文字がある場合はコメントとはみなされません。
正確には、コメントは3つの方法で書くことができます – 完全に一行で書く、コード文の横に書く、複数行のコメントブロックとして書く、です。
以下のセクションでは、それぞれのタイプのコメントについて説明します。
一行コメント
ハッシュ文字(#)で始まり、その後に説明の文章が続くコメントです。
# defining the post code
postCode = 75000
また、コード文の横にコメントを書くこともできます。
次の例は、それを示しています。
# define the general structure of the product with default values
product = {
"productId": 0, # product reference id, default: 0
"description": "", # item description, default: empty
"categoryId": 0, # item category, default: 0
"price": 0.00 # price, default: 0.00
}
Pythonコードのスタイルガイド(PEP8)では、1行の文字数を79文字未満にすることを推奨しています。
実際には、1行あたり70文字や72文字の方が読みやすいので、そちらを推奨しています。
もし、あなたのコメントがこの長さに近づくか超えるようであれば、複数行に分けることをお勧めします。
複数行のコメント
既に述べたように、コメントブロック全体もPythonによって理解されます。
これらのコメントは、あなたのコードを読む他の人のためのインラインドキュメントとして機能し、通常、より詳細に物事を説明します。
技術的には、Pythonは複数行コメントを明示的にサポートしていないので、以下のオプションはいくつかの回避策と考えられていますが、複数行コメントの目的にはまだ機能します。
バージョン1では、以下のように単一行コメントを組み合わせています。
# LinuxThingy version 1.6.5
## Parameters:
## -t (--text): show the text interface
# -h (--help): display this help
バージョン2は、バージョン1よりもシンプルです。
本来は文書作成に使うものですが（これについては後述）、複数行のコメントにも使えます。
"""
LinuxThingy version 1.6.5
Parameters:
-t (--text): show the text interface
-h (--help): display this help
"""
後者のバージョンは、ハッシュ文字ではなく、特殊な引用符(""")で囲む必要があることに注意してください。
共通事項
Pythonのファイルでは、数行のコメントで始めるのが一般的です。
これらの行には、プロジェクトに関する情報、ファイルの目的、開発者または作業したプログラマー、コードに使用されているソフトウェアライセンスが記載されています。
このスニペットは、私がトレーニング用に使用している例の1つから抜粋したものです。
コメントは説明から始まり、私の名前を含む著作権表示、コードの発行年が続きます。
このコードがGNU Public License (GPL)の下でライセンスされていることは、この下に記載されています。
また、私に連絡するために、私の電子メールアドレスもそこに追加されています。
# -----------------------------------------------------------
# demonstrates how to write ms excel files using python-openpyxl
## (C) 2015 Frank Hofmann, Berlin, Germany
# Released under GNU Public License (GPL)
# email frank.hofmann@efho.de
# -----------------------------------------------------------
Docstring コメント
Pythonにはdocstringという組み込みの概念があり、これはあなたが書いたドキュメントをPythonのモジュール、関数、クラス、メソッドと関連付けるための素晴らしい方法です。
docstringは関数、モジュール、またはオブジェクトの頭のすぐ下にコメントとして追加され、関数、モジュール、またはオブジェクトが何を行うかを説明します。
docstringは以下のルールに従うことが期待されています。
- docstringは一行か、複数行のコメントです。後者の場合、最初の行は短い説明文となり、最初の行の後には空行が続きます。
- docstringは大文字で始まり、ピリオドで終わります。
これは、基本的な例です。
def add(value1, value2):
"""Calculate the sum of value1 and value2."""
return value1 + value2
Pythonの対話型ヘルプシステムでは、このdocstringは __doc__ 属性で利用できるようになります。
>>> print add.__doc__
Calculate the sum of value1 and value2.
Doxygen、PyDoc、pdoc、Sphinxのautodoc拡張など、docstringからドキュメントを自動生成するツールはたくさんあります。
これらのツールをどのように使うかについては、次の記事で説明します。
結論
Pythonのコードに適切なコメントを書くことはそれほど複雑なことではなく、持久力が必要なだけです。
それは、あなたのコードを理解しようとする私たち全員と、後日あなたのコードを再訪するときのあなた自身を助けるものです。
私たちがここで与えたアドバイスが、あなたのコードでより良いコメントとドキュメントを作成することを容易にすることを望みます。
謝辞
本論文の作成にあたり，批判的なコメントをいただいたZoleka Hofmann氏に感謝します。