プログラムの可読性を高め、メンテナンスの容易化を図るには、適切な方法でのコメントアウト、ならびに効果的な使い方は重要なポイントです。

本記事では、行単位および複数行にわたるPythonのコメントアウトの方法を、初心者にも理解しやすい形で解説。具体的な記述例を用いて、コメントアウトの基本から応用テクニックまでを段階的に解説し、Pythonコードの品質向上に貢献します。

Pythonのコメントアウト

そもそもコメントとは、プログラムのソースコード内に記述するものの、実際のプログラムの実行には影響を与えないテキストのことです。これらは主にコードの動作を説明するためのメモ書きとして、あるいは特定の部分を一時的に無効化するために使用されます。

つまりPythonに限らず、コメントは他の開発者や将来の自分自身にコードの意図を伝えるための重要なテクニックに位置付けられるものです。このように、ソースコードの一部をコメント化することが、「コメントアウト」と呼ばれます。

コメントアウトの目的

コメントアウトは、コードを説明する注釈として機能するほか、デバッグ、コードの一時的な無効化、古いコードの保持など、さまざまな目的にて使用されています。

優れたコメントアウトは、他の開発者によるコードの理解促進において重要な役割を果たします。また、未来の自分や他人がコードをメンテナンスする際の手助けにもなるものです。

Pythonでは「行単位」「複数行単位」の書き方がある

Pythonのコメントアウトは、主に二つの方法に分類されます。

• 「行単位」のコメントアウト
• 「複数行単位」のコメントアウト

「行単位」のコメントアウトでは、行の先頭に#記号をつけることで、その行全体をコメントとして扱います。単純なメモ書き・説明や一時的なコードの無効化に適している方法です。

# これは単一行のコメントアウトの例です

一方、「複数行単位」のコメントアウトは、'''（シングルクォート3つ）または"""（ダブルクォート3つ）で囲むことで実現され、複数行にわたる説明文やドキュメントの記述に用いられます。

'''
これはクラス、メソッドの機能の複数行による説明です
変数の役割などを明記します
'''
"""
同様にダブルクォートを使った複数行コメントも可能です
クラス、メソッドの説明に利用します
"""

これらの方法を適切に使用することで、Pythonのコードの可読性と管理精度は大きく向上します。

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

実際に、下記のコードにコメントを追加する場合を説明します。

print("Hello")

この場合は、次のように行の始めに#記号を置くことで、その行の残りの部分をコメントアウトします。また、行の途中で#を使うと、#記号以降の行の残りがコメントアウトされます。コードの後に簡単な説明を加える際によく利用されます。

# 以下の処理の説明
print("Hello") #Helloと出力

なお、行内の一部だけをコメントとして記述することはできない点に注意してください。たとえば以下の記述はすべて構文エラーになります。

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

#記号は、行の途中で使用すると、その行の残りすべてをコメントアウトします。特定の範囲だけをコメントアウトすることはできません。また、#記号を複数回使用しても、それぞれの#はその後の行の残りすべてをコメントアウトするため、範囲指定とはなりません。

文字列内の#記号については、コメントアウトとしてではなく文字として扱われます。

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

上記の例では、「Hello #この部分はコメントです World!」と出力されます。「#この部分はコメントです」はコメントとして扱われません。

行単位のコメントアウトの書き方

単一行でのコメントアウトは、#記号のみが利用可能です。次の例は#記号を使ったサンプルコードです。

# 2つの数値の和を返す関数
def add_numbers(a, b): 
        result = a + b
        eturn result

print(add_numbers(12, 4))  # これは 16 を出力します

複数行のコメントアウトの書き方

#記号は、単一行でのみコメントアウトが有効になりますが、実際のプログラミングの場面では、複数行のコメントを記述する場合もあります。可読性を考慮したうえで使い分ける運用となるでしょう。

実際に、下記のコードに「#」を用い、複数行のコメントを追加する場合を説明します。

def reverse_string(s):
        return s[::-1]

print(reverse_string("Hello"))

この場合は、次のようにコメントアウトします。

def reverse_string(s):
        # 与えられた文字列を反転させる関数
        # この関数は削除しないでください
        return s[::-1]

print(reverse_string("Hello"))  # "olleH" を出力します

トリプルクォートを使用した書き方とドキュメンテーション文字列

ドキュメンテーション文字列（またはdocstring）は、Pythonにおいて関数、クラス、モジュールまたはメソッドの目的や動作を説明するために使用される文字列です。これらは定義の直後に記述され、通常はトリプルクォート（''' または """）で囲まれています。

Docstringは、Pythonのhelp()関数や自動ドキュメンテーションツールによって参照され、プログラムの可読性や保守性の向上に役立ちます。

def add(a, b):
        """
        2つの数を加算する関数。
        :param a: 数値1
        :param b: 数値2
        :return: 2つの数の和
        """
        return a + b

Pythonでは、トリプルクォート（''' または """）を使って、次のようにコメントアウトを行えますが、後述する注意点を理解した上での使用を推奨します。

"""
2つの数を加算する関数。
:param a: 数値1
:param b: 数値2
:return: 2つの数の和
"""

注意点として、トリプルクォートを使用したテキストは実際にはコメントアウトではなく、「マルチライン文字列（docstringを含む）」を定義するために使われる特性を意識すべきです。

トリプルクォートは、以下のように関数、クラス、モジュールの説明に使われることが一般的です。

def add(a, b):
        """
        2つの数を加算する関数。
        :param a: 数値1
        :param b: 数値2
        :return: 2つの数の和
        """
        return a + b

特筆すべきは、Pythonインタプリタがトリプルクォートで囲まれたテキストを文字列として扱い、メモリに保持する点です。「コメントアウト」として機能させたい場合、不必要なリソースを消費することになるため注意してください。

また、トリプルクォートを使用する場合、それがdocstringであれば、対象となる関数やクラスの定義と同じインデントレベルに記述する必要があります。これに対して、間違ったインデントを使用すると、Pythonインタプリタが意図しない挙動をする原因となります。行のインデントを必ずそろえるようにしましょう。

class Car:
          def __init__(self, brand, model, year):
                """
                Carクラスのコンストラクタ。
                :param brand: 車のブランド
                :param model: 車のモデル
                :param year: 製造年
                """
                self.brand = brand
                self.model = model
                self.year = year

          def display_car(self):
                """
                車の情報を表示するメソッド。
                """
                return f"{self.year} {self.brand} {self.model}"
      
      # クラスのインスタンスを作成
      my_car = Car("Toyota", "Corolla", 2020)
      
      # インスタンスのメソッドを呼び出し
      print(my_car.display_car())  # "2020 Toyota Corolla"を出力

各ツールのショートカットキーによるコメントアウト

多くのテキストエディタや統合開発環境（IDE）にて、ショートカットキーによるコメントアウトがサポートされています。ショートカットキーの活用は、コードの迅速なコメントアウトに有効です。

ただし、使用するショートカットキーは、使っているエディタやIDEによって異なります。以下に代表的なツールのショートカットキーの例を挙げます。

• Visual Studio Code（VS Code）

  行単位のコメントアウト/アンコメント: Ctrl + / (Windows/Linux), Cmd + / (macOS)
  ブロックコメントアウト/アンコメント: Shift + Alt + A (Windows/Linux), Shift + Cmd + A (macOS)

• PyCharm（および他のJetBrains製IDE）

  行単位のコメントアウト/アンコメント: Ctrl + / (Windows/Linux), Cmd + / (macOS)
  ブロックコメントアウト/アンコメント: Ctrl + Shift + / (Windows/Linux), Cmd + Shift + / (macOS)

• Sublime Text

  行単位のコメントアウト/アンコメント: Ctrl + / (Windows/Linux), Cmd + / (macOS)
  ブロックコメントアウト/アンコメント: Ctrl + Shift + / (Windows/Linux), Cmd + Shift + / (macOS)

• Atom

  行単位のコメントアウト/アンコメント: Ctrl + / (Windows/Linux), Cmd + / (macOS)
  ブロックコメントアウト/アンコメントは特定のショートカットがない

• Jupyter Notebook

  行単位のコメントアウト/アンコメント: Ctrl + / (Windows/Linux), Cmd + / (macOS)
  ブロックコメントアウト/アンコメント:行を選択して行単位のコメントアウトショートカットを使用

Pythonのコメントアウトでエラーになる原因

Pythonコメントアウトに関連する、エラーが発生しやすいケースを挙げていきます。

• 不適切なコメントアウトのシンタックス
• インデントがそろっていない
• コメントアウトされていない / 解除されていない
• コメントアウトが入れ子になっている

不適切なコメントアウトのシンタックス

Pythonでは、#記号を使用してコメントアウトしますが、間違った記号（例：//, /* */）を使用するとエラーになります。Python以外のプログラミング言語を使用しているエンジニアが、ついついミスをしてしまう要因です。

// これはコメントアウトと認識されません。
  /* これもコメントアウトではありません */

正しくは#記号を使用します。

# Pythonでは // /**/　は利用できません。

インデントがそろっていない

コメントアウトしたコードブロック内でインデントが不適切な場合、コメントアウト解除後にインデントエラーが発生する可能性があります。以下はエラーになるサンプルコードです。

def add(a, b):
"""
2つの数を加算する関数。
:param a: 数値1
:param b: 数値2
:return: 2つの数の和
"""
        return a + b

エラーを解消するには、インデントをそろえます。

def add(a, b):
        """
        2つの数を加算する関数。
        :param a: 数値1
        :param b: 数値2
        :return: 2つの数の和
        """
        return a + b

コメントアウトされていない / 解除されていない

コメントアウトしたつもりでも、ブロックコメントが閉じられていなかったり、コメントアウト記号が抜けていたりするとエラーになります。

def add(a, b):
        """
        2つの数を加算する関数。
        :param a: 数値1
        :param b: 数値2
        :return: 2つの数の和

        return a + b

トリプルクォートの閉じ忘れなどのケアレスミスに時間を取られないように注意しましょう。

コメントアウトが入れ子になっている

二重にコメントアウトすることで、コメントアウトとして認識されないコードが発生してしまいます。

def add(a, b):
        """
        2つの数を加算する関数。
        :param a: 数値1
        :param b: 数値2
        """
        この関数で加算後、printで出力すること
        """
        :return: 2つの数の和
        """

        return a + b

多重にコメントが挿入されないように気を付けましょう。