Pythonのコメントアウトとは

Pythonのコメントアウトは、ソースコード内で説明を付けたり、メモ（備忘録）を残したりするための重要な手法です。また、コメントアウト機能を用いて、ソースコードの一部を無効化したい時にも利用します。

コメントアウトは、他のプログラマーにコード内容を伝えたり、自分自身でコードを理解しやすくしたりするために使用されます。この記事では、コメントアウトの基本的な意味や使い方、留意すべきことなどについて解説します。Pythonエンジニアを目指す方はぜひ参考にしてください。

【参考】：Welcome to Python.org

コメントアウトをする理由と注意点

Pythonプログラミングでコメントアウトを行う理由は、主に以下の2つです。コメントアウトを適切に利用して、分かりやすいプログラミングに努めましょう。

コメントアウトを使うと、プログラムの内容や目的、変数の意味、関数の仕様などを自分や他の人に伝えることができます。コメントアウトは、プログラムの可読性や保守性を高めるために重要です。コメントアウトを書くときは、以下の点に注意しましょう。

▪コメントアウトは、プログラムの動作や意図を説明するものであって、コードの内容をそのまま書くものではない ▪コメントアウトは、必要なときに必要なだけ書くものであって、過剰に書くものではない ▪コメントアウトは、プログラムの変更に合わせて更新するものであって、古くなったり矛盾したりするものではない

コメントアウトを使うと、プログラムの一部を一時的に無効化することができます。これは、コードの動作を確認したり、エラーの原因を探したり、別の方法を試すときに便利です。コメントアウトを使ってコードの試行錯誤をするときは、以下の点に注意しましょう。

▪コメントアウトしたコードは、必要に応じて元に戻すか削除するものであって、放置するものではない ▪コメントアウトしたコードは、その理由や目的を明記するものであって、無意味なものではない ▪コメントアウトしたコードは、他のコードとの整合性を保つものであって、混乱を招くものではない

【参考】：Pythonコードのコーディング規約

コメントの種類と使い方

Pythonの「コメントアウト」を知るには、「コメント」と「コメント化」との違いも理解しておく必要があります。それぞれ似ており、混同して使っている人もいますが、それぞれ異なりますので注意しましょう。

コメントの英語である「comment」は「注釈・解説」の意味ですが、Pythonなどのプログラム言語におけるコメントも「注釈・解説」と同じ意味です。PythonやRubyなどでは、コメントを記述する際には「コメント構文」として「#（シャープ）」記号を使用します。

実際には次のように使用します。

# この行はコメントです。プログラム実行時に無視されます。

このケースでは場合、1行目は先頭に#が書かれている場合は「ブロックコメント」と呼び、その行は全てコメントとして、プログラム実行時には無視されます。

print(Hello, World!)  # この部分はコメントです。

このケースでは#以降がコメントであり、#の前のコードは有効で、実行されます。これを「インラインコメント」と呼びます。

「コメント構文」を使用して、ソースコードをコメントに変更することで、一時的にプログラムの無効化をする場合を指します。デバッグなどで、別のコードを利用する場合に、元のコードを残しておきたい場合などに利用します。この場合の主体はあくまでも自分です。

コメント化は状態の変化を表す表現で、「文字列がコメントになる」といった意味で、コメントアウトされた状態を指します。よく「コメント化する」というような使われ方をします。

複数行にまたがる説明文の場合は、‘’‘（シングルクォーテーションを3つ）または、“”（ダブルクォーテーションを3つ）で囲んだ文字列もコメントとして扱われます。以下、複数行のコメント例です。

print(Multi-Line Comment)
"""
この文字列は
複数行です
"""

Pythonのコーディングでは、利用するエディターによってショートカットで簡単にコメント化できます。たとえば、「Jupyter notebook」や「VSCode」では、コードを範囲指定してショートカットキー「 Ctrl 」+「 /」 でコメントアウトできます。

コメントを多用する方は、こうしたエディターを利用すると良いでしょう。

【参考】：Project Jupyter | Home 【参考】：Visual Studio Code – コード エディター | Microsoft Azure

Jupyter Notebookとは？その導入・操作方法を解説

VSCodeとは？定番のコードエディタを他のエディタと比較して解説

ここまで、Pythonのコメント機能について解説しました。改めて整理してみましょう。

1.「コメント」は「文字列」で注釈や解説のこと 2.「コメントアウト」はソースコードをコメントに変更し、自分が行う動作のことで、「ブロックコメント」や「インラインコメント」がある 3.「コメント化」は状態の変化を表す表現で、文字列が「コメントアウト」された状態を指す 4.1行をコメントにする場合は先頭、もしくは途中に「#」を付けると、「#」以降がコメントと認識される 5.複数行をコメントする場合は、文字列を(シングルクォーテーションを3つ）、または '''（ダブルクォーテーションを3つ）で前後から囲む

以上、コメントはコーディングで頻繁に利用しますので、使いながら覚えましょう。

エラーが出た時の対処法

Pythonでコメントアウトを使用した時にエラーが発生することがあります。コメントアウトでよく起こるエラーとその対処法をまとめました。以下、3つのエラーの原因と解決法について解説します。

複数行のコメントアウトがうまくできない、何度やってもエラーが起きるという方は参考にしてください。

インデントエラーが出る場合の原因と解決方法を紹介します。

■ 原因 関数内で三重引用符を使ったコメントアウトを行った際、インデントが正しく行われていないことが原因で起こります。

■ 解決方法  連続するコードでインデントがずれているとエラーになりますので、関数内のコメントアウト部分に適切なインデントを追加します。

【誤り】

def my_function():   
 """関数の説明"""
    print("Hello, World!")

【正解】

def my_function():
    """関数の説明"""
print("Multi-Line Comment")

ダブルクォーテーションエラーが出る場合の原因と解決方法を紹介します。

■ 原因 コメントアウト範囲内でダブルクォーテーションを正しく使わないとエラーが発生します。

■ 解決方法  正しいダブルクォーテーションを使います

【誤り】

""
これはダブルクォーテーションが2つ重なっているためエラーです。
""

【正解】

"""
これは複数行のコメントです。
ここに詳細な説明を記述します。
"""

文字コードエラーが出る場合の原因と解決方法を紹介します。

■ 原因 このエラーメッセージはファイルが「utf-8」以外で保存されている場合に発生します。

■ 解決方法 ソースの1行目に # -- coding: utf-8 -- を追加します。これはマジックコメント（Magic comment） と呼ばれる方式で、通常のコメントとは異なります。例えば、# -- coding: latin-1 -- と記述するとISO-8859-1（latin-1）エンコーディングを指定できます。

# -*- coding: utf-8 -*-
print("こんにちは")

コメントアウトのベストプラクティス

コメントはソースコードに対するメモであり、それぞれのコードの目的や動作内容を記述します。コメントは実際にコードが実行される際には影響はありませんが、ソフトウェア開発のプロジェクトでは極めて重要な要素です。

コメントは他の、共同作業やメンテナンスを行うプログラマーやデバッグを担当するデバッガーなどに対し、Pythonコードの内容や意味を伝え、かつ自身の備忘録としての役目を持ちます。それほどコメントはプログラミングで重要な要素です。

以下、Pythonのコメントに関するベストプラクティスとして紹介します。

誰もが理解しやすい、見やすいコメントを書くには、文章は簡潔で明確に表現しましょう。複雑な説明や冗長なコメントは極力避けましょう。

コードの意図が明確になっていれば、わざわざコメントを付ける必要ありません。あくまでも、複雑で分かりにくいコードや、コードが何を求めているのか分かりにくい時にはコメントで解説を付けましょう。

コメントはコードの説明などをしているものが大半です。コードが変更された場合には、それに対応するコメントも見直して、必要により更新しましょう。古いコメントを残すと誤解を招く可能性がありますので、注意が必要です。

何でもコメントを付ければ良いわけではなく、説明が不要なシンプルなコードは、わざわざコメントを付ける必要はありません。

コメントに強いエンジニアを目指そう

この記事では、Pythonで利用するさまざまな「コメント」について、目的や使い方、コメントにまつわるエラーの理由や対処方法、ベストプラクティスなどについて解説しました。コメント自体はプログラムに直接的な影響はありませんが、理解しやすいコードを書くためにコメントは重要な要素となります。

またコメントにかける手間は、将来の自分や、他の開発者に対する投資でもあり、自らコメントを書くことで、コードに対する理解が深まります。

誰もが分かりやすいコメントを記述するのは、プログラミングスキルの重要な要素であり、魅力的なプログラムを作成し、プログラムの保守性を高める重要な要素です。Pythonエンジニアを目指す方は、ぜひコメントに強い人材を目指しましょう。

Pythonエンジニアとは？仕事内容や年収、未経験でもなれるのか紹介