2.5 コメントを書こう

(1/1)
作文を書く子供のイラスト(女の子)
Pythonに限らないが、プログラムというものは、作成するときより、あとで読まれる回数の方が圧倒的に多い。オープンソースや仕事でつくったプログラムでは、他人が自分のつくったプログラムを読むことが普通である。ある意味、作文と同じなのだ。相手に書いた内容が伝わることが大切だ。
自分専用のプログラムだとしても、書いてから3日もすれば、細かいロジックなど忘れてしまう。
そこで、プログラムの流れや、変数、関数の役割を補足する意味で、プログラム中にコメントを書く習慣を付けよう。

目次

サンプル・プログラム

コメント

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で書いていれば、コメントに日本語やギリシア文字、絵文字を含めることができる。業務用でなければ、絵文字を使って、その時の気分をコメントするのもいいかもしれない。
def sumNumbers(fromInt, toInt):
	"""
	fromIntからtoIntまでの整数を合計する.
	@param	int fromInt	開始値
	@param	int toInt	終了値
	@return	int			合計値
	"""
	n = 0
	for i in range(fromInt, toInt + 1):
		n += i
	return n
Python では、連続する3つのダブルクォーテーション """ があると、再び """ が表れるまでを1つの文字列の塊をみなす。これを文字列リテラルと呼ぶ。
文字列リテラルを使うことで、C/C++言語に備わっている複数行コメント "/* ... */" と同じコメントを書くことができる。

関数についてもコメント記載ルールがあるわけではないが、このシリーズでは、1行目に標題を、2行目以降に細かい機能や例外処理を(このプログラム例では記載はない)、@param ではじまる行に引数とその内容を、@return に戻り値をその内容を記載している。
文字列リテラルは、コメントと異なり文字列データとして扱われるため、関数内部に書くときは、このようにインデントを空ける必要がある。

また、このように関数内に記載した文字列リテラルは、そのオブジェクトのコメントになる。ここでは、組み込み関数の help関数を使い、"help(sumNumbers)" と追記してやると、文字列リテラルの内容を数のように画面に出力する。ヘルプ機能を作るときに役立つだろう。
help()関数 -- Windows, Python
help関数 は、Linuxではmanコマンドのように画面表示する。つまり、qキーを押下すると、次のヘルプへ進む。
help()関数 -- Linux, Python
文字列リテラルについては、「3.8 文字列」で詳しく取り上げる。

バージョンアップ履歴

一定の機能を備えたプログラムやモジュール・ファイルについては、そのバージョンアップ履歴をコメントで書いておくと、不具合対策や、運用チームへ引継ぎを行うときに役に立つ。
# バージョンアップ履歴 ======================================================
def updates():
	"""
	@version 1.1.0 2024/06/15  標題、バージョンアップ履歴等のコメント追加
	@version 1.0.0 2024/06/08  初版
	"""

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


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

標題、権利、注意事項など

一定の機能を備えたプログラムやモジュール・ファイルについては、その標題や機能、知的財産権の主張、注意事項などを書いておくと、オープンソースとして公開したときに役に立つだろう。
def userFunc4_py():
	"""
	Python入門 - 2.5  コメントを書こう
	fromIntからtoIntまでの整数を合計する関数.
	@copyright  (c)studio pahoo
	@author     パパぱふぅ
	@動作環境   Python 3.x + pywebview
	@参考URL    https://www.pahoo.org/e-soul/webtech/python00/py00-02-05.html
	"""

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

練習問題

次回予告

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

コラム:アセンブラ、コンパイラ、インタプリタ

Apple M1
Apple M1
コンピュータの演算や制御を司っているのは CPU(中央演算処理装置)である。インテルの Core i シリーズ、Apple M1などがCPUである。

CPUが直接理解できる命令群(プログラム)のことを機械語(マシン語)と呼ぶ。これはバイナリデータであり、CPUの種類によって変わるため、人間が見ても解読するのは難しい。
はじめて読む8086
機械語の命令を、それに近い英単語(または略号)に置き換えたものがアセンブリ言語と呼ばれるプログラミング言語である。人間が読むことはできるが、CPUの種類によって変わることは同じで、そのCPUの命令体系を熟知していないと理解は難しい。アセンブラ言語で書かれたプログラムは、アセンブラを介して機械語に翻訳され、CPUが直接実行できた。
最初のFORTRAN解説書
最初のFORTRAN解説書
1950年代後半、CPUによる差異を無くし、人間が読みやすいように(作りやすいように)作られた FORTRANCOBOLLISP といったプログラミング言語が登場した。これらは高級言語(高水準言語)と呼ばれ、アセンブラは低級言語(低水準言語)として区別された。高級というのは「高価」という意味ではなく、人間が読める水準にあるという意味だった(高級言語の開発環境は高価ではあったが‥‥)。
Small-Cコンパイラ
当時の高級言語は、コンパイラという仕組みを介して、各々のCPUに合ったアセンブラ言語に翻訳され、最終的にCPUが直接実行できる機械語にしてから実行するというものだった。

PythonはCPUに依存しないが、コンパイラを介してプログラムを実行しているわけではない。実行環境が、ファイルやメモリからプログラムを逐次読み出ししてCPUに実行させている。このような仕組みをインタプリタと呼ぶ。
かつては、コンパイラで作られたプログラムはインタプリタより実行速度が速かったのだが、最近のコンパイラは純粋なアセンブリ言語に翻訳しなかったり(例:Java、C#)、逆にインタプリタでもコンパイル機能を備えたもの(例:PHPのJIT)が登場したことなどにより、両者の境界は曖昧になっている。
(この項おわり)
header