Pythonでのコメントアウト完全ガイド12選

はじめに
●Pythonとは
●コメントアウトとは
●Pythonでのコメントアウトの基本
- ○単行コメントの作り方
  - □サンプルコード1：単行コメントの使い方
- ○複数行コメントの作り方
  - □サンプルコード2：複数行コメントの使い方
●コメントアウトの詳細な使い方
●コメントアウトの応用例とサンプルコード
●Pythonでのコメントアウトの注意点と対処法
●コメントアウトのカスタマイズ方法
- ○エディタによるコメントアウトのショートカット設定
  - □エディタでのショートカット設定方法
- ○docstringの活用方法
  - □サンプルコード12：docstringの活用例
まとめ

はじめに

プログラミング学習の一環として、Pythonでのコメントアウトの使い方は必須の知識です。

しかし、なかなか明確な解説がないため、初心者は混乱することが多いです。

この記事ではPythonでのコメントアウトの基本から応用、カスタマイズ方法までを初心者にもわかりやすく解説します。

●Pythonとは

Pythonは、読みやすさが特徴の高水準プログラミング言語で、その構文はコードの可読性を重視しています。

大規模なシステム開発から小規模なスクリプト作成まで幅広く利用されており、初心者にも扱いやすいとされています。

●コメントアウトとは

プログラミングにおいて、コメントアウトはコードにメモや説明を加える方法の一つです。

コメントアウトされた部分は、コードとしては無視され、プログラムの実行に影響を及ぼしません。

●Pythonでのコメントアウトの基本

Pythonでのコメントアウトは非常に簡単で、行の先頭に「#」をつけるだけです。

その行はPythonによって無視されます。

複数行にわたるコメントアウトを行う場合は、三つのシングルクォートまたはダブルクォートを用います。

○単行コメントの作り方

Pythonの単行コメントは、「#」記号を使って行います。#以降の内容は全てコメントとなります。

□サンプルコード1：単行コメントの使い方

# これはコメントアウトです
print("Hello, World!")  # こちらもコメントです

このコードでは、単行コメントを用いてPythonのprint関数を使った文字列の出力を行っています。

1行目全体と2行目の後半がコメントアウトされているので、実行結果としては”Hello, World!”という文字列のみが出力されます。

○複数行コメントの作り方

複数行のコメントを一度に行うには、三つのシングルクォート(”’)またはダブルクォート(“””)を用います。

□サンプルコード2：複数行コメントの使い方

'''
これは複数行の
コメントアウトです
'''
print("Hello, Python!")

この例では、複数行にわたるコメントを作成しています。

コメントブロックが複数行に渡るため、その中に書かれたテキストは全てPythonによって無視されます。

したがって、コードを実行すると”Hello, Python!”と出力されます。

●コメントアウトの詳細な使い方

○変数に対するコメント

変数に対するコメントは、その変数の目的や使用方法を明記するのに役立ちます。

□サンプルコード3：変数に対するコメントの書き方

# 変数xに数値を代入
x = 10
print(x)  # xの値を出力

このコードでは、変数xに値を代入し、その値を出力しています。

各行のコメントで何を行っているのかを明示しています。このコードを実行すると、10が出力されます。

○関数に対するコメント

関数に対するコメントは、その関数が何を行うのか、どのようなパラメータを取るのか、何を返すのかなど、関数の概要を明確にするために使います。

□サンプルコード4：関数に対するコメントの書き方

# 引数x, yの和を返す関数
def add(x, y):
    return x + y

print(add(3, 5))  # 関数addを使って3と5を足した結果を出力

このコードでは、二つの引数を受け取り、その和を返す関数addを定義しています。

そして、その関数を使って3と5を足す操作を行い、結果を出力しています。

コメントを見ることで、各部分が何をしているのかが一目瞭然です。このコードを実行すると、8が出力されます。

○クラスに対するコメント

Pythonでは、クラスの定義についてもコメントアウトを活用します。

クラスは複数のメソッド（関数）を含むため、コメントアウトはクラス全体の概要だけでなく、各メソッドの働きについても説明することが一般的です。

□サンプルコード5：クラスに対するコメントの書き方

# Employeeクラスは従業員の情報を管理します。
class Employee:
    # __init__メソッドはインスタンスが生成されたときに呼び出されます。
    # ここでは従業員の名前と給与をインスタンス変数として保持します。
    def __init__(self, name, salary):
        self.name = name
        self.salary = salary

    # raise_salaryメソッドは従業員の給与を上げる処理を行います。
    # amountは給与上昇額を示します。
    def raise_salary(self, amount):
        self.salary += amount

このコードでは、Employeeクラスを定義しています。

クラスの説明コメントである「# Employeeクラスは従業員の情報を管理します。」というコメントで、このクラスが何をするものかがひと目でわかります。

また、それぞれのメソッドについても、その機能や引数の説明をコメントとして記述しています。

●コメントアウトの応用例とサンプルコード

次に、実際の開発でのコメントアウトの使用例について見ていきましょう。

開発ではデバッグ、コードのリファクタリング、コードの説明など、コメントアウトを使う場面がたくさんあります。

○デバッグにおけるコメントアウト

プログラムが期待通りに動作しないとき、一部のコードを一時的に無効化（コメントアウト）して、問題を特定するデバッグ作業にコメントアウトはよく使われます。

□サンプルコード6：デバッグ時のコメントアウトの使い方

def calculate_average(numbers):
    total = sum(numbers)
    # リストの要素数が0の場合にエラーが出ないように修正
    # count = len(numbers)
    count = len(numbers) if numbers else 1
    return total / count

このコードでは、リストの平均を計算する関数を定義しています。

デバッグの過程で、リストの要素数が0の場合にエラーが出ることを発見し、その部分をコメントアウトして修正版のコードを書いています。

○コードのリファクタリングにおけるコメントアウト

コードのリファクタリングとは、プログラムの振る舞いを変えずに、コードを読みやすく効率的にするための改善活動です。

Pythonにおけるコメントアウトは、このリファクタリングのプロセスにおいて重要な役割を果たします。

実行しない古いコードを保存したり、新しいコードの導入と並行して比較したりするために、コメントアウトは頻繁に使用されます。

□サンプルコード7：リファクタリング時のコメントアウトの使い方

# 古いコード (これはもう実行しません)
#def add(x, y):
#    return x + y

# リファクタリング後の新しいコード
def add(numbers):
    return sum(numbers)

このコードでは、まず初めにadd関数を定義しましたが、コメントアウトしています。

この関数は2つの数値を受け取り、それらを足して返します。

しかし、リファクタリングを行い、任意の数の数値を受け取り、それらを足す新しいadd関数を作成しました。

この新しい関数は、Pythonの組み込み関数sumを使用しています。

このようにコメントアウトは、コードの変更履歴を追跡するのに役立ちます。

もし新しいコードに問題があった場合、古いコードをコメントアウトしておくことで、必要に応じてすぐに古いコードに戻すことが可能です。

○コードの説明・ドキュメンテーションにおけるコメントアウト

Pythonでのコメントアウトは、コードを他の開発者に説明するためのドキュメンテーションとしても使用されます。

特に複雑な処理や、明らかでないロジックを説明する際に有用です。また、コードの一部が何を行っているのかを表すため、または将来のためにメモを残すためにも使用されます。

□サンプルコード8：ドキュメンテーション時のコメントアウトの使い方

def add(numbers):
    # numbers: 任意の数の数値のリスト
    # 戻り値: 入力されたすべての数値の合計
    return sum(numbers)

このコードでは、add関数が何を行うのか、どのようなパラメータを受け取るのか、そして何を返すのかを説明するためにコメントアウトが使用されています。

これにより、他の開発者がこの関数を見たときに、その目的と使用法をすぐに理解できます。

このように、適切に使用されたコメントアウトは、コードの読みやすさとメンテナンス性を大幅に向上させます。

さらに、将来自分自身が同じコードを見返したときに、何をしていたのかを迅速に思い出すのに役立つでしょう。

●Pythonでのコメントアウトの注意点と対処法

コメントアウトはコードの理解を助ける重要なツールですが、適切に使用しないと逆にコードを混乱させてしまう可能性もあります。

そのため、Pythonでコメントアウトを活用する際にはいくつかの注意点があります。

それでは、それらの注意点とその対処法を具体的なコード例とともに解説していきます。

○コメントの適切な位置

コメントアウトはそのコードの動作や目的を説明するためのものですが、コメントの位置が適切でないとその意味を理解するのが難しくなることがあります。

では、適切なコメントの位置とはどこでしょうか。

それを理解するために、次のコードを見てみましょう。

□サンプルコード9：コメントの適切な位置の例

def add_numbers(x, y):
    # 二つの数値を受け取り、その合計を返す
    return x + y

このコードでは、関数add_numbersが二つの数値を受け取り、その合計を返すという説明のコメントが関数の定義直後に置かれています。

この例では、関数の目的をすぐに理解できるため、コメントの位置は適切です。

一般的に、関数やクラスの定義、重要な操作の前にコメントを置くことが推奨されます。

次に、この関数を呼び出して実行するコードを見てみましょう。

result = add_numbers(10, 20)
print(result)  # 30と表示されます

このコードの最後にあるコメントは、print関数の呼び出しにより表示される結果を表しています。

このように、コメントはその直後のコードの動作や結果を説明するのに役立ちます。

○コメントの明瞭さ

コメントアウトはあなたが何をしているのか、なぜそのように行ったのかを明確に伝えるためのものです。

ですから、コメントは短くても意味が明確であることが重要です。

□サンプルコード10：明瞭なコメントの書き方

def calculate_average(numbers):
    # 入力: 数値のリスト
    # 出力: リストの要素の平均値
    total = sum(numbers)
    count = len(numbers)
    return total / count

このコードでは、関数calculate_averageの目的とその入力と出力が明確にコメントで記述されています。

このように、コードの動作を一言で説明できるならば、それが最も理想的なコメントです。

○過度なコメントアウトの避け方

コードの各部分を説明するコメントは便利ですが、行う操作が自明な場合、過度なコメントは逆に読み手を混乱させる可能性があります。

□サンプルコード11：適切なコメントアウトの量の例

# リストを定義します
numbers = [1, 2, 3, 4, 5]

# リストの要素を合計します
total = sum(numbers)

# 合計をリストの要素数で割ります
average = total / len(numbers)

# 平均を表示します
print(average)

このコードの各行にコメントが付いていますが、それらの操作はPythonの基本的な機能を使用しているため、コメントなしでも容易に理解できます。

このように、コードが自明な操作を行っている場合はコメントを省略することが推奨されます。

●コメントアウトのカスタマイズ方法

Pythonでのプログラミングをより効率的に行うための方法として、コメントアウトのカスタマイズ方法について解説します。

その中でも注目すべき二つのテクニックをご紹介します。

それらは、エディタによるコメントアウトのショートカット設定とdocstringの活用方法です。

○エディタによるコメントアウトのショートカット設定

通常、Pythonのコメントアウトは行頭に「#」を記述することで行いますが、複数行にわたるコメントアウトや、既に書かれたコードを一時的にコメントアウトする際には、一行一行に「#」を記述するのは手間がかかります。

そのような時に便利なのがエディタのショートカット機能です。

たとえば、Visual Studio Code (VSCode)ならば、「Ctrl + /」（Macでは「Cmd + /」）のショートカットキーを使って選択した範囲を一括でコメントアウト、またはコメントアウトの解除を行うことができます。

□エディタでのショートカット設定方法

VSCodeの設定画面でショートカットキーを設定する手順を説明します。

VSCodeの左側のメニューからギアのアイコンをクリックし、「設定」を選択します。
検索ボックスに「keyboard shortcuts」と入力します。
「Open Keyboard Shortcuts」をクリックします。
検索ボックスに「toggle comment」と入力します。
「Editor: Toggle Line Comment」の行にマウスを移動し、右側に表示されるペンのアイコンをクリックします。
任意のキーコンビネーションを入力し、Enterキーを押します。

この設定により、キーボードから手を離すことなく、効率的にコメントアウトを行うことが可能になります。

○docstringの活用方法

Pythonには、関数やクラス、モジュールなどに複数行にわたるコメントを書くための特別な機能があります。

それがdocstringです。

これは三重引用符（””” または ”’）で囲むことで定義します。

docstringを利用すれば、関数やクラスの目的、引数、戻り値などを詳しく説明することができます。

この説明文は、Pythonの組み込み関数help()で表示することができます。

これにより、他の開発者や将来の自分がコードを見たときに、その目的や挙動をすぐに理解することが可能になります。

□サンプルコード12：docstringの活用例

下記のコードでは、二つの数字を足し合わせる関数add_numbersのdocstringを示しています。

この例では、関数の目的、引数の説明、戻り値の説明をそれぞれコメントとして記述しています。

def add_numbers(num1, num2):
    """
    二つの数字を足し合わせる関数

    引数：
    num1: 足し合わせる最初の数字
    num2: 足し合わせる次の数字

    戻り値：
    二つの数字の和
    """
    return num1 + num2

このコードを実行後、help関数を使用して関数の説明を表示すると以下のようになります。

help(add_numbers)

Help on function add_numbers in module __main__:

add_numbers(num1, num2)
    二つの数字を足し合わせる関数

    引数：
    num1: 足し合わせる最初の数字
    num2: 足し合わせる次の数字

    戻り値：
    二つの数字の和

これにより、関数の詳細な説明をコード内に保持しつつ、必要な時に簡単に参照できることがわかります。

それぞれの関数やクラスが何をするためのものか、どのように使用すべきかを詳細に記述することで、コードの可読性とメンテナンス性が大幅に向上します。