プログラムの可読性を上げるためにコメントの記述がよく行われます。
今回は、Pythonにおけるコメントの記述スタイルと、コメントを記述する上での心構え、効果的なコメントの使い方について解説します。
コメントの必要性
コメントはプログラムの可読性を上げるための補足説明です。
プログラムは将来に渡って機能追加やバグ対応が付きまといますので、「どんな考え方でプログラムを書いているか」が非常に重要になります。
プログラムは１つの結果を得るための書き方がいくつも存在します。
他人が書いたプログラムは他人の試行パターンによって成り立っているので、複雑なものになるほど他人が中身を把握することは難しいのです。
また、プログラミング業界では、「３日も経てば自分も他人」とかいう言葉が存在します。
人によっては３日が１週間、３ヶ月などの言葉に変わることはありますが、「時間が立てば自分が書いたプログラムは他人が書いたものと同じく、中身が分からなくなる」ため、未来の自分のためにもコメントは重要です。
コメントの役割
コメントはプログラムの可読性を上げることが目的ですが、これを利用してデバッグやコーディングの手順メモとして活用することもあります。
特にコーディングの手順メモとしてコメントを書く方法は、初心者にとってお勧めです。
あらかじめ手順を考え、それを明記することで頭の整理ができますし、コメントはそのまま残しておくだけで良いので、複雑な処理を考える場合には是非お試しください。
コメントの種類
コメントには、インラインコメントとブロックコメントの２種類が存在します。
インラインコメントは # から始まり、１行単位でコメント化する場合に用います。
一方、ブロックコメントは改行を含む複数行をまとめてコメント化する場合に用います。
インラインコメント
インラインコメントは、＃以降を無視する仕様であるため、インデントは気にすることなく、好きな位置に置くことが出来ます。
for x in range(10):
#２倍する
x = x * x
print(x)
for x in range(10):
#２倍する
x = x * x
print(x)
ただし、見難くなるので基本的にはインデントに合わせて記述するほうが良いでしょう。
逆にインデントを無視して行頭に＃を持っていくことで、コメントを目立たせることができます。
例えば、デバック目的で一時的にコメントアウトしておき、デバッグが済んだらコメントを外す場合にこの方法を用いると、コメントを外す箇所が見つけやすいという利点があります。
更に一歩進んで、デバッグ用のコード（例えばprint文など）を挿入した時、そこが見つけやすいように’$’ や ‘@’ などの文字をコメントとして羅列しておくことで、後から削除しやすくなります。
#$$$$ print(data) #$$$
ブロックコメント
ブロックコメントは シングルクォートを３つ(”’ ～ ”’)、あるいは ダブルクォートを３つ (“”” ～ “””) で囲みます。
複数行をコメントアウトしたい場合、 いちいち 先頭に# を付けるのは面倒な場合、ブロックコメントを使います。
また、ブロックコメントには「関数、クラス、メソッドの使い方を記述」するという大切な役目があります。
そして、「関数、クラス、メソッドの使い方を記述する」場合、大きく４つのスタイルが存在します。
reStructureTextスタイル
reStructureText は XML やHTMLと同様のマークアップ言語（文書の構造を表すための言語）です。
このスタイルを用いてコメントを書くと、このスタイルに対応したツールを使って関数やメソッド仕様書の様なドキュメントを自動作成したり、JyupterやVisual Studio Code 等でメソッド名を入力した時、ツールチップとして表示してくれるようになります。
Pythonでは、この reStructureText スタイルで記述したコメントのことを、docstring と呼んだりしています。
尚、ブロックコメントは ’’’ 又は “”” のどちらでも良いと言いましたが、reStructureText として認識されるのは “”” で囲った時のみとなります。
class Normalization:
"""
データ正規化用クラス
"""
def normalization(self,data):
""" データの正規化
引数で渡された値を正規化して返す
:param data: 正規化したいデータ
:type data: list of float
:rtype: list of float
:return: 正規化されたデータ
"""
# 最大値と最小値を求める
minval = min(data)
maxval = max(data)
#正規化する
return [(x - minval) / (maxval - minval) for x in data]
nm = Normalization()
print(nm.normalization([5,8,3,2,5,6,7]))
reStructuredTypeスタイル（引数の型は TypeHintで記述）
reStructuredType スタイルにおいて、引数の戻り値と型を TypeHint で記述する方法もよく用いられます。
TypeHint は 関数名の定義時に型を指定する機能で、次の様に記述します。
def 関数名(変数名 : 変数の型) -> 戻り値の型
ただし、Python 3.8 以前ではリスト、タプル、辞書を指定した時、その要素の型までは指定できないのでご注意ください。
def normalization(self,data:list) -> list:
""" データの正規化
引数で渡された値を正規化して返す
:param data: 正規化したいデータ
:return: 正規化されたデータ
"""
Numpyスタイル
Numpy はじめとし、多くの標準ライブラリで使われているスタイルです。
引数の数が多いと縦に長く伸びていくため、たくさんスクロールしないとソースコードが見れないという難点はあります。
def normalization(self,data:list) -> list:
""" データの正規化
引数で渡された値を正規化して返す
Parameters
-----------------
data: list of int
正規化したいデータ
Returns
-----------------
list of float
正規化されたデータ
"""
Googleスタイル
Numpy スタイルに比べて引数や戻り値の記述は半分で済みますので、すっきりした印象があります。
今のところこのスタイルにお目にかかったことはありませんので、まだまだ少数派です。
個人的には、この記述の方が好きです。
def normalization(self,data:list) -> list:
""" データの正規化
引数で渡された値を正規化して返す
Args:
data(list of int): 正規化したいデータ
Returns:
list of float: 正規化されたデータ
"""
まとめ
今回は Phton のコメントについての書き方と応用方法を含めて解説しました。
インラインコメントは主にソースコードの注釈、ブロックコメントは関数、クラス、メソッドの説明用途で使用するケースが多いです。
また、単純に注釈として利用するだけではなく、デバッグ等で一時的に特定のソースコード部分を無効化したり、処理手順を書いて頭を整理するなどの使い方もありますので、是非参考にしてください。
この記事が皆様のプログラミングの一助になれば幸いです。