Pythonに限らずコードの説明を書くために、コメントが使われます。
この記事では、Pythonのコメントの書き方やコメントの書く意味などについて説明します。
コメントの書き方
Pythonでコメントを書くには「#」を使います。
「#」からその行の終わりまでがコメントになります。
「#」から後ろがコメントになるので、スペースがあってもなくても同じです。
#この行はコメントになります
# この部分はコードとして認識されません行の途中からでも「#」から後ろはコメントになります。「#」の前はコードとして認識されます。
以下を実行すれば「ここは表示される」と出力されます。
# print('コメント') この行はすべてコメントになります。
print('ここは表示される') # 行の途中からでもコメントになります。「’」または「”」で囲んだ部分は文字列になるので、文字列の中の「#」はコメントにはならず、ただの文字として扱われます。
# ここはコメントになります。
print('文字列の中の#はコメントにはなりません')実行した出力結果は以下のようになります。
文字列の中の#はコメントにはなりません複数行のコメント
Pythonでは、複数行のコメントはありません。すべての行に「#」を書く必要があります。
# print('ここからコメント')
# print('これはコメント')
# print('これもコメント')
# print('ここもコメント')
# print('ここまでコメント')コメントではないですが、「’’’」または「”””」（「’」や「”」を3個連続したもの）で囲むことで、複数の行を文字列リテラルにできます。
# これはエラーになります
print("これは
エラーに
なります")
# これは実行できます
print("""これは
実行
できます""")これを利用すれば、コメントアウトのように使うことができます。
以下を実行すれば「Hello, world!」とだけ表示されます。
"""
ここは文字列リテラルになる
print('コードとしては実行されない')
"""
print('Hello, World!')リテラルは、ソースコード内に直接書かれた値や文字のことです。文字列のリテラルを文字列リテラルと言います。
以下のコードだと「Bob」と「18」がリテラルで、「name」と「age」が変数です。変数「name」に、「Bob」という文字列リテラルを代入しています。
name = 'Bob'
age = 18注意点として、「”””」で囲った部分はコメントではなく、文字列リテラルです。コメントのように無視されるわけではないので、インデントがあっていないとエラーになります。
以下の例では、「hello1()」と「hello3()」は問題ありませんが、「hello2()」はエラーになります。
def hello1():
# これはコメントなので問題ない
print('Hello, World1!')
def hello2():
""" これは文字列リテラルなのでエラーになる """
print('Hello, World2!')
def hello3():
""" これはインデントがあっているので問題ない """
print('Hello, World3!')Docstringsとは
これを使ったものに「Docstrings（ドキュメント文字列）」というものがあります。クラスや関数などの定義の最初に出てくる文字列リテラルで、一般的にはダブルクォート「”」3つで表現します。
クラスや関数の説明として使われます。
def hello(name):
"""
あいさつする
@param name 名前
"""
print('Hello ' + name + ' !')この文字列リテラルは、「__doc__」で呼び出すことができます。
def hello(name):
"""
あいさつする
@param name 名前
"""
print('Hello ' + name + ' !')
print(hello.__doc__)実行した出力は、以下のようになります。
あいさつする
@param name 名前
コメントの考え方
コメントは、コードの中に書けるドキュメントです。うまくコメントを使うことで、コードを読む人の理解を助けます。
わかりにくいコードやバグ修正のためのテクニカルなコードは、コードの説明をコメントで書くことでそのコードの目的がわかります。
しかし、コードが変わったときには、そのコードに対応するコメントも修正する必要があります。コードだけ変更された場合、コメントはそのコードをわかりにくくするかもしれません。
意味のない多すぎるコメントも考え物です。
以下の2つのコードは全く同じものですが、コメントはコードの理解を助けていないどころか、コードを読みにくくしています。
# aに3を代入する
a = 3
# bに4を代入する
b = 4
# cにaとbを掛けて2で割ったものを代入する
c = a * b / 2
# cを表示する
print(c)a = 3
b = 4
c = a * b / 2
print(c)ただ、このままだと何をしているコードかわかりません。以下のようなコメントがあれば、三角形の面積を計算しているのだと理解できます。
# 三角形の面積の計算
# 底辺
a = 3
# 高さ
b = 4
# 三角形の面積
c = a * b / 2
# 三角形の面積を表示する
print(c)変数名を工夫すれば、コメントがなくてもコードを読むだけで何をしているのかわかります。
# 三角形の面積の計算
base = 3
height = 4
triangleArea = base * height / 2
print(triangleArea)目指すべきは、コードのドキュメント化です。コード自体が何をしているのかを表現すれば、コメントは必要なくなります。
まとめ
Pythonでコメントは「#」を使う。
「’」や「”””」を3つ連続して囲むと、「文字列リテラル」を複数行に書くことができる。
クラスや関数の定義の最初に書かれた「文字列リテラル」はDocstringsと呼ばれ、「__doc__」で呼び出すことができる。
コメントは、コードの理解を助けるために書く。
コードが変われば、コメントも修正する。
コメントがなくても理解できるようなコードを書く。
参考
PEP8 – Style Guide for Python Code
note.nkmk.me – Pythonのコメント、コメントアウトの書き方
