2.5 コメントを書こう

（2024年7月20日）docstringについて加筆

1. サンプル・プログラム
2. コメント
3. docstring
4. バージョンアップ履歴
5. 標題、権利、注意事項など
6. 練習問題
7. 次回予告
8. コラム：アセンブラ、コンパイラ、インタプリタ

ダウンロード

Python では、ハッシュ # から行末をコメントとして認識し、プログラムには何の影響も与えないようになっている。また空行も何の影響も及ぼさない。

# メイン・プログラム =======================================================
# キーボードから入力する（文字列）．
startStr = input("開始=")
goalStr  = input("終了=")

このプログラムでは "メイン・プログラム =======", "キーボードから入力する（文字列）．" がコメントとして認識される。

# 文字色のエスケープシーケンス
COLOR_CYAN   = "\033[36m"	#シアン
COLOR_GREEN  = "\033[32m"	#緑色
COLOR_YELLOW = "\033[33m"	#黄色
COLOR_END    = "\033[0m"	#終了

ハッシュ # から行末までがコメントとして認識されるから、このプログラムでは "文字色のエスケープシーケンス" は1行丸ごと、"シアン", "緑色"‥‥はハッシュから行末までをコメントとして認識する。
Python ではコメントの書き方ルールはないが、変数のコメントは、その変数の右や、コメントが長いときには、変数の上1行に書くといいだろう。

プログラムをUTF-8で書いていれば、コメントに日本語やギリシア文字、絵文字を含めることができる。業務用でなければ、絵文字を使って、その時の気分をコメントするのもいいかもしれない。

Python では、連続する3つのダブルクォーテーション """ があると、再び """ が表れるまでを1つの文字列の塊をみなす。これを文字列リテラルと呼ぶ。
文字列リテラルを使うことで、C/C++言語に備わっている複数行コメント "/* ... */" と同じコメントを書くことができる。これを Python では docstring と呼ぶ。

docstring は、ユーザー定義関数やユーザー定義クラスの説明に使うことが多い。
公式の PEP 257 で書き方を定めているが、概念的に過ぎる部分が多いので、この連載では Googleスタイルを利用することにする。

def sumNumbers(fromInt, toInt):
	"""fromIntからtoIntまでの整数を合計する．

	Args:
		fromInt(int):	開始値
		toInt(int):		終了値
	
	Returns:
		int: 合計値
	"""
	n = 0
	for i in range(fromInt, toInt + 1):
		n += i
	return n

文字列リテラルは、コメントと異なり文字列データとして扱われるため、関数内部に書くときは、上記のようにインデントを空ける必要がある。
Googleスタイルは下記のような構造をもつ。

"""1行説明文
(空行)
より詳しい説明
(空行)
Args:
    引数1の名前(引数1の型): 説明1
    引数2の名前(引数2の型): 説明2
...
(空行)
Returns:
    戻り値の型: 説明
(空行)
Raises:
    例外の名前: 説明
(空行)
Examples:
    関数やクラスの使い方
(空行)
Attributes:
    クラス属性1の名前(属性1の型): 説明1
    クラス属性2の名前(属性2の型): 説明2
...
(空行)
ToDo:
    今後実装予定の処理など
(空行)
Note:
    その他何でも
"""

Args セクションは引数を説明する。インスタンスを示すselfは省略する。省略可能な引数は 引数の名前(引数の型, optional): 説明 のように記載する。
Returns セクションは戻り値を説明する。
Raises セクションは例外処理を説明する。
Examples セクションは関数やクラスの使い方を説明する。
Attributes セクションはクラスの属性を説明する。
ToDo セクションは今後実装予定の処理などを記載する。
Note セクションには、その他何でも書くことができる。
なお、すべてのセクションを書く必要はない。

このように関数内に記載した文字列リテラルは、そのオブジェクトのコメントになる。ここでは、組み込み関数の help関数を使い、"help(sumNumbers)" と追記してやると、文字列リテラルの内容を数のように画面に出力する。ヘルプ機能を作るときに役立つだろう。

help関数 は、Linuxではmanコマンドのように画面表示する。つまり、qキーを押下すると、次のヘルプへ進む。

文字列リテラルについては、「3.8 文字列」で詳しく取り上げる。

一定の機能を備えたプログラムやモジュール・ファイルについては、そのバージョンアップ履歴をコメントで書いておくと、不具合対策や、運用チームへ引継ぎを行うときに役に立つ。

# バージョンアップ履歴 ======================================================
def updates():
	"""バージョンアップ履歴

	Version:
		1.2.0: 2024/07/19  docstringをGoogleスタイルに変更
		1.1.0: 2024/06/15  標題、バージョンアップ履歴等のコメント追加
		1.0.0: 2024/06/08  初版
	"""

# ヘルプ情報を表示
help(userFunc4_py)
help(sumNumbers)
help(updates)

バージョンアップ履歴の書き方にルールはないのだが、このシリーズでは、プログラム・ファイルの末尾にユーザー定義関数 updates に文字列リテラルを使ってバージョンアップ履歴を書いている。
このプログラムの中で、"help(updates)" と追記してやると、文字列リテラルに記したバージョンアップ履歴を画面に表示する。

一定の機能を備えたプログラムやモジュール・ファイルについては、その標題や機能、知的財産権の主張、注意事項などを書いておくと、オープンソースとして公開したときに役に立つだろう。

def userFunc4_py():
	"""fromIntからtoIntまでの整数を合計する関数．

	Copyright:
		(c)studio pahoo, パパぱふぅ
	
	Environment:
		Python 3.7 or after + Matplotlib
	
	Note:
		Python入門 - 2.5  コメントを書こう
		https://www.pahoo.org/e-soul/webtech/python00/py00-02-05.html
	"""

これもルールはないのだが、このシリーズでは、プログラム・ファイルの冒頭にプログラム・ファイル名に似せたユーザー定義関数を置き、文字列リテラルを使って上記の情報を記載する。

本章は、データの入出力、四則演算と算術関数、ユーザー定義関数、そして入力バリデーションを通じて、Pythonを使って簡単なプログラムを作るところまでを履修した。
このあとは、Pythonの文法を掘り下げて、より高度なプログラムを作ることを目指す。次章では、変数と式について説明する。

かつては、コンパイラで作られたプログラムはインタプリタより実行速度が速かったのだが、最近のコンパイラは純粋なアセンブリ言語に翻訳しなかったり（例：Java、C#）、逆にインタプリタでもコンパイル機能を備えたもの（例：PHPのJIT）が登場したことなどにより、両者の境界は曖昧になっている。