note.nkmk.me

Pythonのコメント、コメントアウトの書き方

Date: 2018-06-20 / tags: Python

Pythonで説明をコメントとして記述したり不要なコードをコメントアウトしたりする場合は#を使う。

トリプルクォート(三重引用符)による文字列がコメントとして利用されている場合もあるが、関数に説明を加える公式の仕組みであるdocstring以外であえてトリプルクォートを使う理由はない。

ここでは以下の内容について説明する。

  • #によるコメント、コメントアウト
    • インラインコメント
    • ブロックコメント(行全体)
  • PEP8(コーディング規約)の推奨ルール
  • トリプルクォートの複数行コメントとしての利用
  • 関数アノテーションによるコメント
スポンサーリンク

# によるコメント、コメントアウト

インラインコメント

#から行末までは実行時に無視される。#より前のコードは有効。

a = 1  # comment
source: comment.py

行の途中の一部分を範囲指定してコメントとすることはできない。例えばコメント中にさらに#が含まれていてもそこでコメントが終わるわけではなく、最初の#以降はすべてコメントとみなされる。

a = 1  # comment # b = 2
source: comment.py

ブロックコメント(行全体)

#を行頭に書くとその行すべてがコメントとみなされ実行時には無視される。

# a = 1
source: comment.py

対象の行すべての行頭に#を書けば複数行に渡ってコメントアウトされる。

a = 1
# b = 2
# c = 3
# d = 4
e = 5
source: comment.py

PEP8(コーディング規約)の推奨ルール

PEPはPython Enhanthment Proposal(Python拡張提案)の略で、PEP8ではコーディング規約(スタイルガイド)について書かれている。#を使ったコメントについても推奨のルールが記載されている。

PEP8のルールを守らなくても文法上エラーになるわけではないが、所属組織やプロジェクトのコーディング規約が特にない場合はPEP8に従っておくといいと思う。

pydocstyleやflake8などのコードチェッカーにおけるエラーコードとともにコメントの書き方のルールを示す。

インラインコメント

E261: at least two spaces before inline comment

文とコメントの間は少なくとも2つのスペースを置く。

3つ以上でもOKだが、これは下の例のようにコメントの位置を揃える場合のため。不要なスペースはないほうがいい。

# No:
a = 1 # comment

# Yes:
a = 1  # comment

a = 1      # comment
xyz = 100  # comment
source: comment.py

E262: inline comment should start with '# '

インラインコメントは#とスペースひとつから始める。#のあとにスペースが無くても2つ以上あってもダメ。

# No:
a = 1  #comment
a = 1  #  comment

# Yes:
a = 1  # comment
source: comment.py

ブロックコメント

E265: block comment should start with '# '

ブロックコメントはコメント内でインデントされたテキストでない限り#とスペースひとつから始める。#のあとにスペースが無いとダメ。

E262と異なりスペース2つ以上でもOKだが、これはコメント内でのインデントのため。不要なスペースはないほうがいい。

# No:
#comment

# Yes:
# comment
#     indented comment
source: comment.py

E266: too many leading '#' for block comment

先頭の#はひとつだけ。

# No:
## comment

# Yes:
# comment
source: comment.py

トリプルクォートの複数行コメントとしての利用

関数(defブロック)の先頭の文字列に説明を記述するdocstring(ドキュメンテーション文字列)という仕組みがある。詳細は以下の記事を参照。

def test(a, b):
    '''docstring
    description
    '''
    print(a)
    print(b)
source: comment.py

シングルクォート'、ダブルクォート"を3つつなげたトリプルクォート(''', """)で囲むことで改行を含めた文字列を生成することができるため、docstringではトリプルクォートが使われることが多い。

文字列を単独で記述してもコードの処理に影響を与えないので、docstring以外でもトリプルクォート(三重引用符)が複数行のコメントやコメントアウトとして利用されている場合がある。

a = 1
'''
b = 2
c = 3
d = 4
'''
e = 5
source: comment.py

トリプルクォート(三重引用符)はあくまでも文字列なので、#によるコメントのように実行時に無視されるわけではない。例えば、インデントされているブロックの中でトリプルクォートをコメントとして利用しようとする場合、インデントをあわせないとエラーになる。

インデントがあっているとOK。

def test(a, b):
    print(a)
    '''
    comment line1
    comment line2
    comment line3
    '''
    print(b)
source: comment.py

インデントがあっていないとエラーIndentationError

def test(a, b):
    print(a)
'''
comment line1
comment line2
comment line3
'''
    print(b)

# IndentationError: unexpected indent
source: comment.py

#によるコメントは実行時に無視されるのでインデントがあっていなくてもエラーにはならない。が、コードとしての可読性を良くするにははインデントをあわせたほうがいい。

def test(a, b):
    print(a)
    # comment line1
    # comment line2
    # comment line3
    print(b)

def test(a, b):
    print(a)
# comment line1
# comment line2
# comment line3
    print(b)
source: comment.py

いずれにせよトリプルクォートはコメントではなく文字列なので、公式の仕組みであるdocstring以外ではコメントとしてトリプルクォートを使わないほうが無難だと思う。

VS Codeなどのエディタでもショートカット(command + /またはcontrol + /)によるコメントアウトでは一行の場合も複数行の場合も#が使われる。

関数アノテーションによるコメント

Python3.0以降では関数アノテーション(Function Annotations)という仕組みによって関数の引数や返り値にアノテーション(注釈)となる式を記述することができる。

def func_annotations_type(x: str, y: int) -> str:
    return x * y

関数アノテーションは単なる注釈なので、上の例のように型を記述した場合でも実行時に型チェックされたりはしないが、IDEやエディタによってはその情報をもとに処理を行うものもある。

詳細は以下の記事を参照。

スポンサーリンク
シェア
このエントリーをはてなブックマークに追加

関連カテゴリー

関連記事