【Python】コメントアウト・コメントの書き方

このような疑問にお答えします。

Python は他のプログラミング言語と比べて読みやすい言語ですが、それでも複雑なコードだと視認性は一気に低下します。

そこで便利なのがコメント処理です。

コメント部分は「プログラムの処理上、何も書いていないこと」と同じ扱いになります。

そのため、コードの説明などをコメントとして書き加えればコードの内容を即座に理解できます。

「プログラムは書く時間よりも読む時間の方が多い。そのため、読みやすさは極めて重要である」

読みやすいコードを書くため、Python におけるコメントアウトの方法をマスターしていきましょう。

本記事では以下の内容をお伝えします。

それぞれ、解説していきます。

“#” を使ったコメント

最も基本的なコメントが、#を使ったものです。

上記について、詳しく解説していきます。

ブロックコメント

１行まるごとコメントにしたい場合は、文頭に#を書きます。

# プログラミング言語を入力
code_type = "python"

上記の場合には1行目がコメントと解釈され、無視されます。

2行目は#がないので、プログラムコードとして実行されます。

インラインコメント

コードの途中で#を入れることで、#以降がコメントとして解釈されます。

code_type = "python"  # プログラミング言語を入力

つまり、code_type = "python"だけが実行されることになります。

トリプルクオート（”””）を使ったコメント

Python の関数では、クオートを3つ並べてコメントを書き込みます。

なお"""は厳密にはコメントではなく、文字列としての扱いです。

使える文字列は"と'の２種類

トリプルクオートで使える文字は"（ダブルクオート）と'（シングルクオート）の二つです。

以下のように、コメントをクオート３つ繋げて囲みます。

# シングルクオートを使った場合
def single_quate():
    '''
    ここにコメントを書く
    '''
    return None

# ダブルクオートを使った場合
def double_quate():
    """
    ここにコメントを書く
    """
    return None

どちらを使っても意味は同じです。

文字列扱いなので無視されない

#を使ったコメントと違って、トリプルクオートは文字列として解釈されます。

なので、厳密にいうとプログラム上無視されるわけではなく文字列として読み込まれることになります。

そのため、以下のように複数行の文字列を変数に格納したい場合に使えます。

# メール本文
body = """
お世話になっております。
株式会社 〇〇〇〇 の 〇〇です。
・・・
何卒、よろしくお願いいたします。
"""

インデントを合わせる必要がある

以下の場合には「関数箇所のインデント」に合っていないので、インデントエラーになってしまいます。

# ダブルクオートを使った場合
def double_quate():
"""
ここにコメントを書く
"""
    return None

ぱっと見で違和感があるので気づきやすいと思いますが、念のため理解しておくと良いでしょう。

関数アノテーションでのコメント

Python3.0 以降では、関数の引数や戻り値の「型」や「オブジェクトの種類」を明示するのに使われます。

強制力はないので別の種類の「型」や「オブジェクト」が渡されたとしてもエラーにはなりませんが、コードを読む時の理解の助けにはなります。

関数アノテーションの書き方

パラメータの後にコロン（:）と型名を記載し、アロー（->）の後に戻り値の型名を記載します。

具体例な書き方は以下の通り。

def int_to_string(param: int) -> str:
    return str(param)

実は、関数アノテーションを入れたとしても実際の型検査や型強制は行われません。

関数アノテーションを使うことによるメリットは、IDE などの静的型チェックツールで赤下線などが表示されることによりエラーチェックが強化されることです。

開発中に型系の齟齬に気づきやすくなるという点で有効だと考えれば良いと思います。

Python の標準スタイルガイドのルール

Pythonの標準スタイルガイド（PEP8）には、以下のようなコメントに関する記述ルールが記載されています。

ルールを破ってもエラーになりませんが、ルールを守ることで「違和感のない可読性の高いコード」を書くことができるようになります。

以下、PEP8 に記載の推奨ルールをご紹介します。

#とコメントの間のスペース数

#の後にはスペース1つを入れます。

# プログラミング言語を入力
code_type = "python"

上記の例では、#とプログラミング言語を入力の間のスペースは１つです。

2つ以上のスペースを入れると間の抜けた感じになってしまうので、ここは統一しておきましょう。

コードとコメントの間のスペース数

コードとコメントの間には「2つ以上のスペース」を開けることが推奨されています。

なぜなら、スペースを入れることにより「コード」と「コメント」の境界線がパッと見で判断することができるからです。

このほうが、コードレビュー時に断然読みやすい。

例えば、以下の例ではコードの終わり（"python"）とコメントの間に2つのスペースを入れています。

code_type = "python"  # プログラミング言語を入力

PEP8 では「2つ以上のスペース」とされていますが、僕がこれまで見てきたコードでは3つ以上のスペースが開けられることはあまりない気がします。

#の数

先頭の#は１つだけにします。

# 正しいコメントの書き方

## 誤り
### 誤り

僕は以前これを知らずに、マークダウンの見出しような雰囲気で##や###のように書いていましたが、PEP8 的には非推奨なので注意しましょう。

これを知ってから、僕は PEP8 に従った書き方に変えました。

コメントはコードと矛盾してはいけない

コメントは、コードの内容を説明するものでなければなりません。

そのため矛盾したコメントは混乱を生むだけであって、書くべきではありません。

# xの値を減らす
x = x + 1

上記のコードを見ると、「え、どういうこと！？」と感じるはずです。

長文のコードを書いていると混乱してきて、変なコメントを書いてしまうこともあると思います。

後から読んだ人が混乱してしまわないよう、コメントを入れる際には気をつけてみましょう。

常にコードの変更時に更新する

仕様変更・コード修正の際に、コードだけではなくコメントも更新しましょう。

コードが正しければ、コメントは間違っていても正しく動いてしまいます。

意外とコメントはないがしろにされてしまうことも多いので、こちらも後からコードを読む人の可読性を確保するためコメントもしっかりと更新するようにしましょう。

コーディング規則を統一するためのアドバイス

以上のルールを守ることで、読みやすく保守しやすいプログラミングコードを開発することができます。

ところが今回紹介したものだけでもかなり細かいルールだと感じた方は多いのではないでしょうか？

そのような場合に便利なのが「フォーマッタ」です。

フォーマッタとは PEP8 などに違反する部分を自動的に整形してくれるツールで、以下のようなものがあります。

Visual Studio Code では、これらのフォーマッタを有効化しておくことで保存（Command + S）するたびに整形するよう設定することも可能です。

僕は Black と isort の組み合わせを好んで使っています。

フォーマッタの詳しい説明は、後日別記事でご紹介する予定です。

正しいルールを覚えて読みやすいコードを書こう！

ここまでご紹介したコメントの書き方を実践していただければ、かなり読みやすいコードがかけるようになっているはずです。

今回はコメントに特化した内容をお伝えしていきましたが、コードは後から読み返す時間の方が多いため結構重要なポイントだと思います。

ぜひ、今回の書き方をマスターしてコーディングスキルを上げていきましょう！