Pythonソースコードの実例で分かる「本当に良いコメント」の書き方とは？：プログラマーが知るべき「良いコメント」の条件【第4回】

ソースコードに対する理解を補助するのが、適切なコメントだ。コメントを書くためにプログラマーが理解しておくべき原則を、実例とともに解説する。

[Matthew Grasberger，TechTarget]

　プログラマーはソースコード内に、補助的なテキストを「コメント」として挿入可能だ。読みやすく、メンテナンスしやすいソースコードにするには「良いコメント」が欠かせない。具体的には、どのようなコメントが良いコメントなのか。

「本当に良いコメント」のPython実例はこれだ

併せて読みたいお薦め記事

連載：プログラマーが知るべき「良いコメント」の条件

• 第1回：「コメント」の“本当の意味”を誤解していないか？
• 第2回：Pythonのソースコードで考える「こんなコメントは無駄なだけで無意味」
• 第3回：「良いコメント」って結局何？　「悪いコメント」に隠れた“深刻な問題”とは？

ソースコードの書き方

• 「Python」と「Go」のソースコードを比べて分かる「インデント」の違いとは？
• 命令型プログラミングと宣言型プログラミングの「ソースコード」の違いとは？

　ソースコードの内容をそのまま繰り返すだけのコメントは、有益な情報をほとんど提供しない。良いコメントとは、読んだ人が「プログラム実行時に何が起こるのかを理解できる」コメントだ。

　良いコメントの例を見てみよう。以下は、プログラミング言語「Python」の教材用に書かれたソースコードだ。取得した日付情報を、さまざまな形式の日時表現の文字列に変換する関数を定義している。

# プログラムが稼働するマシンの所在地の日付を取得する（タイムゾーンは考慮しない）
# 注意：dateはプログラムの冒頭でインポート済み
def stringdate():
   today = date.today()
   date_list = str(today).split('-')
   # 「月-日-年」の形式で文字列を作成する
   date_string = date_list[1] + "-" + date_list[2] + "-" + date_list[0]
   return date_string

　プログラムの概要は以下の通りだ。

• 3行目
  • 関数の名前を「stringdate」と定義する。
• 4行目
  • 今日の日付（date.today()）を変数「today」に代入する。
• 5行目
  • today中にある日付のデータを年、月、日に分解して、変数「date_list」に代入する。
• 7行目
  • date_list中にある年、月、日のデータを使って、日付を「月-日-年」の形式で変数「date_string」に代入する。
• 8行目
  • date_stringを呼び出し元に渡す。

　このソースコード内にあるコメントは「ソースコードが『何をするか』ではなく、『何のためのものか』が分かるコメントを書く」という、良いコメントの原則を反映している。ここでのコメントの役割は、Pythonを学ぶプログラマーが、関数に対する理解を深めることだ。以下にコメントの詳細を示す。

• 1行目のコメントでは、このソースコードで定義する関数の概要を説明し、関数を使うプログラマーが知るべき重要な条件を共有する。
• 2行目のコメントでは、プログラムの先頭でクラス（データや操作をまとめたオブジェクトの設計図）「date」をインポート（読み込み）済みであることを説明する。
• 6行目のコメントでは、date_stringに代入する文字列の内容を説明する。

---

　次回は、これまでに説明した「良いコメント」の条件をまとめる。

TechTarget発　エンジニア虎の巻

米国TechTargetの豊富な記事の中から、開発のノウハウや技術知識など、ITエンジニアの問題解決に役立つ情報を厳選してお届けします。