13. コメント

Python コメントアウトの書き方を徹底解説(複数行/関数、Jupyter notebookでのショートカットキーなど)

更新日:

Pythonにおけるコメントアウトの方法を初心者向けに解説していきます。行単位・複数行単位のコメントの書き方やショートカットキー、関数のコメントの書き方・表示方法など、コメントについてはこれだけを読んでおけば良いよう、徹底的に解説していきたいと思います。
 
コメントとは、プログラムに関する注釈で、プログラムコードを読みやすくするメモとして利用します。

またプログラムがうまく動かない時など、原因のコードを突き止めるためにプログラムの中で一時的に実行させたくないコードをコメントにして動かない状態にすることもあります。(これをコメントアウトと言います。)

プログラムの一部ずつをコメントアウトし、動作しないようにすることにより、どこでエラーが起きているかがわかります。

Pythonのコメントアウトには、行単位のコメントアウト、複数行単位のコメントアウトの2種類があり、それぞれ詳しく確認していきましょう。

または関数やクラスなどにdocstringという説明文を記述することができます。これらはヘルプとしてコーディング中に参照できるので非常に便利です。docstringも詳しく解説していきます。

 

Pythonにおける行単位のコメントアウトの書き方

Pythonでは行単位のコメントは、#に続けて記述します。#以降は行の終わりまでコンピュータは無視し、実行されません。

# Hello, world!を表示する
print "Hello, world!"

1行目の「# Hello, world!を表示する」は、#に続いて記述されているのでコメントと認識され、プログラムとしては実行されません。一方で、次の2行目に記述されている「print "Hello, world!"」には#は含まず、プログラムと認識され、実行されます。このように、#の後に続いて記述された内容がコメントになります。
 
 
一方で、行の途中に#が記述されている場合はどうでしょうか。

print "Hello, world!"  # Hello, world!を表示する

この場合も、#以降、行の終わりまでがコメントとして認識されるということに違いはありません。
「print "Hello, world!"」はプログラムとして実行され、#に続いて記述されている「# Hello, world!を表示する」の箇所はコメントとして扱われます。

 
 

Pythonにおける複数行単位のコメントアウトの書き方

Pythonでは複数行にまたがるコメントアウト記号はありませんが、プログラム中に記述された文字列は実行に影響を及ぼさないため、これを利用してクォーテーションを使って複数行単位のコメントを記述します。具体的には、'''(シングルクォーテーション3つ)あるいは"""(ダブルクォーテーション3つ)で囲まれた部分がコメントアウトされます。

'''
この行はコメントです。
この行もコメントです。
'''

 

ただし、クォーテーションを用いたコメントアウトではインデント(字下げ)に注意する必要があります。#はインデントなしで使うことができますが、クォーテーションを用いたコメントは必ず直前の行と同じインデントで記述しましょう(通常、インデントには半角スペース4つが使われます。)。

for i in range(3):
      print("コメントテスト")
'''
このコメントはエラーになります。
'''
      print(i)

上の例では、for文によって繰り返される処理のブロック外にコメント(文字列)が書かれているためにエラーとなってしまいます。
 
つまり、赤い点線で囲ったコメントのインデントが、青い点線で囲まれたfor文の繰り返し処理で記述されている処理とズレている為に、エラーが発生しています。

以下のように適切にインデントをつけることで解決することができます。

for i in range(3):
      print("コメントテスト")
      '''
      このコメントはOKです。
      '''
      print(i)

 
 

Jupyter notebookでのショートカットキーによるコメントアウトと除去

Jupyter notebookでは、記述したコードを選択して、ショートカットキー Ctr + / (スラッシュ) を押すとコメントアウトすることができます。複数行を選択してCtr + / を押すと、複数行に渡って一括してコメントアウトされます。
 
またコメントアウトされている行が選択されている状態でCtr + / を押すと、コメントアウトが除去されます。こちらもコメントアウトされている複数の行を選択してCtr + / を押すと、選択された全ての行のコメントアウトが除去されます。
 
例えば、次のような3行からなるコードがあり、3行とも選択した状態でCtr + / を押すと、

In [1]: a = 1
...: b = 2
...: c = a + b

 
次のように3行とも、行の先頭に#が付き、コメントアウトされたことがわかります。ここから、3行を選択した状態でさらにCtr + / を押すと、

In [1]: # a = 1
...: # b = 2
...: # c = a + b

 
次のようにコメントアウトが解除されます。

In [1]: a = 1
...: b = 2
...: c = a + b

 
このようにショートカットキーを利用することで、複数の行のコードを簡単にコメントアウトしたり、コメントアウトを解除したりすることができます。

 
 

Pythonでの関数、クラスなどのコメント/ドキュメントの書き方

Pythonでの関数やクラスなどへのコメントは、関数やクラスなどの定義の先頭に記述します。
 
これらのコメントは、docstring(ドックストリング、ドキュメンテーション文字列)と呼ばれています。docstringは通常のコメントとは異なり、ヘルプとして表示することができ、プログラムのコーディングの際に、関数やクラスの説明として参照して活用することができます。
 
関数の詳しい説明は、以下の章を参照ください。


 
docstringの記述方法は、関数では以下のようにダブルクォーテーションを3つ並べて「”””」のように書きます。シングルクォーテーションを3つ並べても構いません。これら「”””」と「”””」の間に関数の説明を記述していきます。またクラスでも同様に記述します。

def 関数(引数):
       “””
       ここにdocstringを記述
       “””
       関数のロジック
return 返り値

 
注意点としては、docstringは関数(クラス)の先頭に記述する必要があります。次のように、関数(クラス)の先頭以外に記述するとdocstringとは認識されず、通常のコメントと認識されてしまいます。これにより、後述するdocstringに関する機能を利用することができません。

def 関数(引数):
       関数のロジック
       “””
       ここの説明文は、docstringとは認識されません。
       “””
       関数のロジック
return 返り値

 
 

docstringを用いた関数へのコメントの記述と規約・ルールの例(見やすい書き方の例)

簡単な関数にdocstringを書いてみましょう。引数a、bを受け取り、その和 a + bを返す関数addを定義し、その中にdocstringを記述します。docstringを記述する際には、何らかの規約・ルールを定め、全ての関数に対して同じ形式で記述していくことで、後から見返した時にわかりやすくなります。

In [2]:
...: def add(a, b):
...:       """
...:       引数a、bを受け取り、その和 a + bを返す関数
...:
...:            引数
...:       --------------
...:       a : int, float
...:            足し算する1つ目の数値
...:       b : int, float
...:            足し算する2つ目の数値
...:
...:            返り値
...:       --------------
...:       a + b : int, float
...:            引数a、bの和a + b
...:       """
...: return a + b

上の例では、規約・ルールとして、最初に「引数a、bを受け取り、その和 a + bを返す関数」というように関数の説明を記述しています。
 
次に「引数」の後に、引数のデータ型や説明を書いていきます。そして最後に「返り値」の後に同じく、返り値のデータ型と説明を記述しています。
 
 

Jupyter notebookでのdocstringで記述したコメントの表示方法

先ほど関数に記述したdocstringはどのように参照できるのでしょうか。Jupyter notebookで参照する方法はいくつかありますが、その中から主な2つを紹介します。Jupyer notebookなどPythonの開発環境準備に関する詳しい説明をご覧になる場合、こちらのリンク「Python入門 - インストールと実行」から参照ください。先ほどdocstringを書き込んだ関数addを元に、docstringの内容を表示してみます。
 

helpでのdocstringの表示

1つ目は、helpを用いてdocstringを表示します。次のようにhelpの中にdocstringを表示したい関数を入力して実行します。

help(関数)

 
実際の例として、先ほど作成したadd関数で試してみると、

In [3]: help(add)

次のようにdocstringで記述した内容が表示されます。

Out[2]:

 
 

Jupyter notebookでのショートカットを利用したdocstringの表示

もう1つのdocstringの表示方法は、ショートカットキーを利用したものです。Jupyter notebookで関数を入力し、Shift + Tabキーを押すと、その関数のdocstringが表示されます。
 
まずは関数「add()」を入力します。この時点では、docstringは表示されていません。

この関数の説明をみたい場合、Shift + Tabキーを押します。すると、次のようにdocstringで記述した内容が表示されます。

さらにShiftキーを押したまま、もう一度Tabキーを押すと、docstringの詳細な内容が展開されて表示されます。

このようにしてdocstringを参照することにより、コーディングの途中で関数の詳細な説明を確認することができるので、非常に便利です。

 

Pythonにおけるコメントアウトの説明は以上になります。コメントアウト以外についても、Pythonに関する重要なトピックについて学んでいきたいと考えておられる方には、次のページをお勧め致します。
>> Python3で学ぶデータ分析・AI・機械学習(Python入門編)
 
この本では、今後データサイエンスや機械学習、AIを学習していきたいと考えている方へ向けて、それらの知識の習得に欠かせないPythonの基本的なトピックに重点を絞り、チュートリアル形式で解説しています。特にPythonでデータ分析・AI・機械学習を学ぶ上で欠かせない基礎となる重要な事項を取り上げています。
 

-13. コメント

Copyright© AI-interのPython3入門 , 2019 All Rights Reserved.