プログラムの可読性を高め、メンテナンス性の向上を図るためにも適切なコメントの記載とコメントアウトの利用は重要なポイントです。
本記事では、行単位や複数行など、Pythonにおけるコメントアウトの方法を、初心者にもわかりやすく解説していきます。具体的な記述例や解説を参考に、コメントアウトの基本と応用を理解して、Pythonコードの品質を向上させましょう。
目次
1.Pythonのコメントアウト機能とは
まず前提として「コメントアウト」とは、ソースコード内には記述されているものの、実際の処理に影響を与えないテキストのことです。用途には以下のようなものがあげられます。
対象コードの動作や処理の説明
メンテナンスやエラーに関する対応などの共有事項
要するにコメントはPythonに限らず、各プログラミング言語において「他の開発者や保守・管理の人員などに対して、コードの意図を伝えるための要素の1つ」にあたるのです。そして、ソースコードの一部をコメント化する操作を「コメントアウト」と呼びます。
コメントアウトの役割
前述で説明した「開発者がソースコードの意図を共有する」役割以外に、修正前のコードの保持や一時的な処理の無効化、解析ツールのチェック対象からの除外などのさまざまな役割を果たしてくれる機能です。
ログなどと違って基本的にはお客様が見ることはない部分にはなりますが、開発者にとってはソースコードの修正や改良などの作業においては重要な役割を果たすことになります。また、エンジニアであれば、複数のプロジェクトに参画する場合もあるため、自分にとっても助けになる存在です。
Pythonのコメントアウトは「行単位」と「複数行」の2種類
Pythonでコメントアウトを行う方法は大きく分けて2種類あります。
それが「行単位」と「複数行」です。
用途も分けて使用され、行単位は「単純なメモ書きや説明と一時的なコードの無効化」、複数行は「複数行にわたる説明やドキュメント化のための記述」というような違いがあります。
コメントアウトの方法は以下の通りです。
【行単位】
# この行はコメントアウトされます。 |
【複数行】
‘’’ シングルクォーテーションで囲まれた範囲はすべてコメントアウトされます。 変数の説明などに用いられることが一般的です。 ‘’’ “”” ダブルクォーテーションも同様に囲まれた範囲をコメントアウトします。 クラスやメソッドの説明への利用が多いです。
|
それぞれの方法を使い分けることで自分以外にも可読性の高いソースコードにすることができるでしょう。
2.Pythonのコメントアウトの書き方
ここからは各方法でのコメントアウトの基本的な書き方と注意事項について解説していきます。
Pythonのコメントアウト：行単位と指定箇所以降
行単位でコメントアウトを行うのは「#（シャープ）」をつけることで可能です。
記述する場所は主に2種類で「行の先頭」「処理の後」になります。
実際にコード例でみていきましょう。
# 以下の処理の説明 print(2*6) # 2×6の計算結果を出力 |
実行結果
12 |
上記の1行目が「行の先頭」に記述する場合、2行目が「処理の後」に記述する場合になります。ここで注目すべきなのが2行目のprint処理は実行されるという点です。
行の先頭に「#」を記載した場合は以降の文字がすべてコメントアウトされますが、行の途中に「#」をつけた場合は以降の文字がコメントアウトされます。
この特性から注意すべきなのは「処理の後」に記載するという点です。例えば、以下のように処理の途中で記載した場合はエラーとなります。
# 以下の処理の説明 print(2*6 # 2×6の計算結果を出力) |
実行結果
print(2*6 # 2×6の計算結果を出力) ^ SyntaxError: '(' was never closed |
これは処理の途中で記載されたためにprintの「)」を認識することができずに発生しているエラーです。
このように行または指定箇所以降がコメントアウトされるのが「#」になります。記述位置を間違えるだけで実行できなくなるため注意して使いましょう。
Pythonのコメントアウト：複数行
複数行のコメントアウトは「’’’ または ”””」のトリプルクォートで行うとは書きましたが、こちらの方法は前述でも少し触れたようにドキュメント化のために使用することが主な用途です。
これらは実際には「複数行文字列」として扱われ、純粋なコメントとは異なる性質を持っています。そのため、ドキュメントに含める必要はないが、複数行のコメントを書く必要がある場合には「#」で対応します。
例えば、以下のようにドキュメント化するまでもないような関数に関するメモ書きを複数行にわたり記載する場合などです。
def reverse_str(s): # 与えられた文字列を反転させる関数 # この関数は削除しないでください return s[::-1]
|
例のようにクラスやメソッド内で「#」のコメントアウトを使用する場合にはインデントに注意が必要になります。
まず前提として、「#」でのコメントアウトはインデントがずれていても行の先頭にさえあれば、エラーになることはありません。しかし、以下のようにインデントの有無で可読性が低下することがあるため注意が必要です。
【インデントあり】
class Test: # これはテスト用のクラスです。
# 与えられた文字列を反転させる関数 # この関数は削除しないでください return s[::-1] |
【インデントなし】
class Test: # これはテスト用のクラスです。
# 与えられた文字列を反転させる関数 # この関数は削除しないでください return s[::-1] |
エラーが起こらないからといって、意味もなくインデントなしで記載することはせっかくのコメントの意図をわかりにくくしてしまいます。コメントごとの意図を自分以外にもしっかりと伝えるための工夫を心がけましょう。
Pythonのコメントアウト：複数行まとめてとドキュメンテーション文字列
Pythonにおいて「’’’ または ”””」のトリプルクォートでの複数行のコメントアウトは正確に言うと、コメントアウトではありません。「ドキュメンテーション文字列（またはDocstring）」というクラス、モジュールまたはメソッドの目的や動作を説明する文字列として扱われます。
重要なのは普通のコメントアウトとの違いで、トリプルクォートで囲まれたコメントは「マルチライン文字列」としてメモリに保持されることです。複数行のコメントを記載したいからといって、トリプルクォートを多用していると不要なリソースを使用することになるため注意して使用してください。
Docstringの主な用途は以下の通りです。
コードの可読性向上
ドキュメンテーションの作成
自動化テストの構築
それぞれ詳しく見ていきましょう。
コードの可読性向上
これは単純な理由で以下の例のようにクラスやメソッドの用途や使用する変数に関する説明はコードの可読性を高めるためには重要な要素になります。
def sum(a, b, c): """ 3つの数の合計を計算する関数。 :param a: 数値1 :param b: 数値2 :param c: 数値3 :return: 3つの数の和 """ return a + b + c |
このように「関数の機能」「引数の概要」「返却する値」を明記することで、修正の際に必要な情報を得ることが可能です。また、対象のメソッドやクラスが自分に必要な処理を持っているかを確認しやすくもなるため、ルールを決めた運用をすれば、開発の効率化を見込めるでしょう。
ドキュメンテーションの作成
Pythonではhelp関数を使用することでDocstringとして記載された内容を抽出することができます。
# 先ほどの例から抽出 print(help(sum)) |
実行結果
sum(a, b, c) 3つの数の合計を計算する関数。 :param a: 数値1 :param b: 数値2 :param c: 数値3 :return: 3つの数の和 |
ここでは詳しくは触れませんが、Docstringの要素を抽出してドキュメントを作成するライブラリやモジュールは複数あるため、興味があれば調べてみると良いでしょう。
自動化テストの構築
Pythonには「doctest」というドキュメント文字列内の例を使用した、コードテストをするモジュールがあります。
以下のようにテストしたいメソッドのDocstring内に「>>>」を先頭につけて、実行条件と期待する結果を記載し、doctestのtestmodをという関数で実行することが可能です。
import doctest
""" 3つの数の合計を計算する関数。 :param a: 数値1 :param b: 数値2 :param c: 数値3 :return: 3つの数の和
8
18 """ return a + b + c
|
成功している場合は特に何も表示されません。詳細を見たい場合は「python ファイル名 -v」で実行すれば、以下のように詳細が表示されます。
Trying: sum(1, 2, 5) Expecting: 8 ok Trying: sum(4, 6, 8) Expecting: 18 ok 2 items had no tests: main main.reverse_str 1 item passed all tests: 2 tests in main.sum 2 tests in 3 items. 2 passed. Test passed. |
これによって基本的な動作チェックを行うこともできるので、使いこなせればメソッド単体でのテストを専用にコードを作成せずとも行うことが可能です。
関連記事
【Python初心者向け】Pythonで作れるものや入門用のサンプルコード、おすすめの参考書を紹介！
3.各ツールにおけるPythonのコメントアウトショートカットキー
行単位/範囲指定で複数行のコメントアウトショートカットキー
各Pythonのエディタツールにおいてコメントアウトのショートカットキーが用意されています。ショートカットキーで行うコメントアウトは「選択中の行単位」と「クラスやメソッドなどのコードブロック単位」の2種類です。
それぞれのエディタツールで見ていきましょう。
Visual Studio Code（VS Code）
指定範囲 | 方法 |
|---|---|
行単位 | Windows/Linux：Ctrl + / macOS：Cmd + / |
ブロックコメントアウト | Windows/Linux：Shift + Alt + A macOS：Shift + Cmd + A |
PyCharm（および他のJetBrains製IDE）
指定範囲 | 方法 |
|---|---|
行単位 | Windows/Linux：Ctrl + / macOS：Cmd + / |
ブロックコメントアウト | Windows/Linux：Ctrl + Shift + / macOS：Cmd + Shift + / |
Sublime Text
指定範囲 | 方法 |
|---|---|
行単位 | Windows/Linux：Ctrl + / macOS：Cmd + / |
ブロックコメントアウト | Windows/Linux：Ctrl + Shift + / macOS：Cmd + Shift + / |
Atom
指定範囲 | 方法 |
|---|---|
行単位 | Windows/Linux：Ctrl + / macOS：Cmd + / |
ブロックコメントアウト | 特定のショートカットキーはない |
Jupyter Notebook
指定範囲 | 方法 |
|---|---|
行単位 | Windows/Linux：Ctrl + / macOS：Cmd + / |
ブロックコメントアウト | 行を選択して行単位のコメントアウトショートカットを使用 |
コメント解除（アンコメント）の方法
上記で紹介したコメントアウトのショートカットキーはほとんどの場合、コメント解除（アンコメント）にも使用できます。コメント解除の方法は、コメントアウトされている行や範囲を選択し、同じショートカットキーを再度実行するだけです。
たとえば、VS Codeでは以下のように機能します：
1. コメントアウトされていない行に対して「Ctrl + /」（macOSでは「Cmd + /」）を実行 → 行先頭に「#」が追加されてコメントアウトされる
2. すでにコメントアウトされている行に対して「Ctrl + /」（macOSでは「Cmd + /」）を実行 → 行先頭の「#」が削除されてコメント解除される
この仕組みは多くのエディタで共通しており、上記で紹介した各エディタでも同様のショートカットキーでコメント解除が可能です。
複数行をまとめてコメント解除する場合も同様に、コメントアウトされている複数行を選択し、対応するショートカットキーを実行するだけで、選択したすべての行からコメント記号が一度に削除されます。
なお、Pythonのコードファイルを直接編集する場合（エディタを使用しない場合）は、コメントを解除するには「#」記号を手動で削除するか、三重引用符で囲まれた複数行文字列の場合は、その三重引用符を削除する必要があります。
4.Pythonのコメントアウトにおけるエラー原因
Pythonで複数行コメントアウトができない
「#」でなく、「’’’ または ”””」のトリプルクォートを使用する場合やコメントアウトの方式を間違えている場合などに発生する可能性のある事例です。
インデントエラー
以下の例のようにインデントを揃えていないとトリプルクォートではエラーが発生します。
def sum(a, b, c): """ 3つの数の合計を計算する関数。 :param a: 数値1 :param b: 数値2 :param c: 数値3 :return: 3つの数の和 """ return a + b + c |
実行結果
""" ^^^ IndentationError: expected an indented block after function definition on line 143 |
不正な記述のコメントアウト
Python以外では「//」「/* */」などでコメントアウトが可能ですが、Pythonでは「#」と「’’’ または ”””」のトリプルクォートのみしかコメントアウトとして認識しないので注意です。
そのため、以下のような記載はエラーになります。
// これはコメントアウトと認識されません。 /* これもコメントアウトではありません。 */ |
実行結果
SyntaxError: invalid character '。' (U+3002) |
また、以下のようにコメントの閉じ忘れや「’ または “」の個数違いなどでもエラーになるので注意です。
【閉じ忘れ】
def sum(a, b, c): """ 3つの数の合計を計算する関数。 :param a: 数値1 :param b: 数値2 :param c: 数値3 :return: 3つの数の和
8
18
return a + b + c |
【個数違い】
def sum(a, b, c): "" 3つの数の合計を計算する関数。 :param a: 数値1 :param b: 数値2 :param c: 数値3 :return: 3つの数の和
8
18
“” return a + b + c |
実行結果
SyntaxError: unterminated triple-quoted string literal |
関連記事
Pythonのvirtualenvとは？仮想環境の作成・管理・応用・エラー対応までわかりやすく解説
5.Pythonのコメントにおけるベストプラクティス
これまでの解説からもわかる通りコメントはメンテナンス性やコードの可読性を高めるために重要な要素になります。記載にミスがなければ、ソースコード実行に影響は出ませんが、開発作業においては欠かすことはできません。
ここでは、Pythonにおけるコメントのベストプラクティスを紹介します。
簡潔でわかりやすいコメントを心がける
コメントは誰もが理解できる形式と内容で簡潔に表現することが大切です。自分以外もが理解することのできるコメントにすることで開発チームや保守管理チームなどの同じシステムに関わる方々の業務効率を向上することも見込めます。
不必要なコメントは書かない
そもそも、簡潔な処理や目的が明確な処理に関してはコメントは必ずしも必要ではありません。複雑でわかりにくいコードまたはチーム内で決めたルールの範囲内でコメントは記載するようにしましょう。
ソースコードとコメントは同時に修正する
コメントは基本的にソースコードの説明や補足など、セットで管理されているものが大半です。そのため、ソースコードの修正が行われた場合には、同時にコメントの修正も確認し、必要に応じて行いましょう。
もし古いコメントをそのままにするとメンテナンスで処理が修正前に戻されてしまうことも発生してしまうため、注意が必要になります。
コメントを書きすぎない
コメントは多ければ多いほど良くなるというような万能なものではありません。そのため、コメントをつけるかどうかの取捨選択は重要です。
適切な箇所に簡潔なコメントを心がけましょう。
関連記事
6.まとめ
ここまでPythonのコメントアウトについて紹介していきました。Pythonに限らずプログラミングコードにおけるコメントは重要な役割を持ちます。自分だけでなく開発に関わるあらゆる人員が目にすることになるため、用途や役割を理解して使用することが大切です。
また、関わるプロジェクトによってはルールがあいまいな場合もあると思います。その際に闇雲にコメントを追加するのではなく、チームや企業内でしっかりと相談して、不必要なコメントが増えないように心がけましょう。
本記事が皆様にとって少しでもお役に立てますと幸いです。
「フリーランスボード」は、数多くのフリーランスエージェントが掲載するITフリーランスエンジニア・ITフリーランス向けの案件・求人を一括検索できるサイトです。
開発環境、職種、単価、稼働形態、稼働日数など様々な条件から、あなたに最適なフリーランス案件・求人を簡単に見つけることができます。
単価アップを目指す方や、自分の得意なスキルを活かせる案件に参画したい方は、ぜひ「フリーランスボード」をご利用ください。