Pythonでのコメントとコメントアウトの書き方をまとめました

19/02/11 17:49:54 19/04/08 11:48:07

コメントとは、ソースコードに対する日本語や英語の説明のことです。第三者にソースコードの内容をパッと見でわかるようにすることや、自分自身が後から見返した際にわかりやすくする、といった目的があります。

また、先にコメントを書いておくことで、どのような実装をすれば良いのか明確にしておく、といった使い方も可能です。先にロジックを日本語や英語で理解しておいた方がプログラミングしやすいので、先にコメントを書いておくのはオススメのやり方です。

このように利便性が高く必須と言っても過言ではないコメントですが、ソースコードにそのまま日本語や英語でコメントを書くと当然バグにつながります。なぜなら、システム上はソースコードと関係ないものだからです。

そこで、コンピューターに「ここはソースコードとは無関係です。」「コメントなので処理しないでください。」と伝える必要があります。プログラミング言語ごとに方法は微妙に異なるのですが、このページではPythonでの方法を紹介します。

ただし他のプログラミング言語でも基本的な考え方は同じなので役立ちます。

1 コメントアウトとは
- 1.1 コメントアウトの方法
2 docstringの使い方
3 案件量が豊富なアルマサーチ

コメントアウトとは

上で説明した通りコメントはコンピューターに読み飛ばしてもらう必要があるのですが、このことを「コメントアウト」と呼びます。

せっかくコメントを書いたのにコメントアウトし忘れてバグにつながった、といったケースは案外多いため、間違えないよう注意したいところです。

コメントアウトの方法

Pythonのコメントアウトの方法は主に二種類で、「#」の後にコメントを書く方法と、「’(シングルクォーテーション)」もしくは「”(ダブルクォーテーション)」で囲う方法があります。このように書くと「#」を書くだけの方が便利なように感じられるかもしれません。

実際その通りで「#」でのコメントアウトを使う機会がもっとも多いかと思いますが、「#」でのコメントには欠点もあります。それは、1行しか適用されないということです。「#」でのコメントアウトはコメントを囲うわけではないため、終わりを指定することができません。

そのため、自動的に1行でコメントアウトが終わるよう設定されているのです。なので1行コメントを書く際は「#」が便利なのですが、コメントアウトが複数行に渡る場合、行ごとに「#」を書くのは冗長で見にくいです。

そこで便利になるのが「’(シングルクォーテーション)」もしくは「”(ダブルクォーテーション)」で囲う方法です。なので、基本的にはコメントが1行なら「#」でコメントアウト、複数行に渡る場合は「’」や「”」で囲う、と決めておくと良いかもしれません。

実際の開発現場でのルールはプロジェクトによりけりで、1行の「#」コメントしか認めていないプロジェクトなどもあります。また「’」と「”」については、どちらでコメントアウトするか明確に決められているケースが多いです。

個人開発ならコメントアウトの方法も自由ですが、後から他人がソースコードを見る可能性もあるため「’」と「”」についてはどちらかに統一しておいた方が良いかもしれません。ここまでの説明を実例で紹介すると以下のサンプルコードのようになります。

print("Hello world!")
# display "Hello" with print function.

このソースコードを実行すると、「Hello world!」と出力されます。次に、複数行の場合だと以下のようになります。

print("Hello world!1")
'''
print("Hello world!2")
print("Hello world!3")
print("Hello world!4")
'''

このソースコードを実行すると、「Hello world!1」だけが出力されます。

以降はコメントアウトされているため、出力されません。単純なコメントアウトだけなら以上で終了で、これだけ押さえておけば特に問題はありません。

ルールに従って記号を入力するだけなので、非常に簡単かと思います。しかしより応用的なコメントの使い方もあります。エンジニアでも知らない人がいるくらいのものではあるのですが、プロジェクトによっては以降で紹介する方法がルール化されているかもしれません。

個人開発ではそれほど使用しないかもしれませんが、こんな使い方もある、ということで紹介しておきます。

docstringの使い方

応用的なコメントの使い方というのが、docstringというものです。docstringは関数やクラスに対する説明文で、通常のコメントに近いです。では通常のコメントアウトと何が違うのかというと、docstringとしてコンピューターに認識されるとdocstringの形式で表示されます。

普通にコメントアウトしても特に問題はないのですが、docstringで表示すると関数やクラスの説明がわかりやすくなる、くらいに捉えておくと良いかと思います。また通常のコメントアウトよりもレイアウトが統一されるため、属人性を排除できるというメリットもあります。

書き方としては、’(シングルクォーテーション)」もしくは「”(ダブルクォーテーション)」を三つずつで囲みます。サンプルコードとしては以下のようになります。

"""
docstringの使い方を説明するためのモジュールです。
"""
def func():
　　　"""
　　　この関数は文字列Hello worldをプリントします。
　　　"""
　　　print("Hello world")

class myclass():
　　　"""
　　　docstirngの使い方を説明するのためのクラスです。
　　　"""
　　　def __init__(self, val):
　　　　　　self.value = val

　　　def class_func(self):
　　　　　　print("This is class_func")
func()
t = myclass("test")
t.class_func()

このまま実行すると通常のコメントアウトと同じでコメントとして扱われるだけなのですが、ファイル保存してインポートした際に違いが現れます。

インポートした後help関数でファイル名を指定すると、以下のようにdocstringが表示されます。

先程作ったtest.pyをモジュールとしてimportしてみましょう。

そしてimportした後、help関数でdocstringを表示させてみましょう。

Help on module test:
NAME
　　　test - docstringの使い方を説明するためのモジュールです。
CLASSES
　　　builtins.object
　　　　　　myclass

　　　class myclass(builtins.object)
　　　| docstringの使い方を説明するためのクラスです。
　　　|
　　　| Methods defined here:
　　　|
　　　| __init__(self, val)
　　　| Initialize self. See help(type(self)) for accurate signature.
　　　|
　　　| class_func(self)
　　　|
　　　| ----------------------------------------------------------------------
　　　| Data descriptors defined here:
　　　|
　　　| __dict__
　　　| dictionary for instance variables (if defined)
　　　|
　　　| __weakref__
　　　| list of weak references to the object (if defined)
FUNCTIONS
　　　func()
　　　　　　この関数は文字列Hello worldをプリントします。
DATA
　　　t = <test.myclass object>
FILE
　　　c:\users\desktop\test.py