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

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

2023年07月02日 09時30分 公開
[Matthew GrasbergerTechTarget]

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

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

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

 良いコメントの例を見てみよう。以下は、プログラミング言語「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エンジニアの問題解決に役立つ情報を厳選してお届けします。

ITmedia マーケティング新着記事

news053.jpg

「docomo Ad Network」 高LTVユーザーのみに広告配信ができる顧客セグメントを追加
D2Cは顧客生涯価値が高くなることが見込まれるセグメントを抽出し、新たなセグメント情報...

news135.png

インターネットの利用環境、女性の66%は「スマホのみ」――LINEヤフー調査
LINEヤフーが実施した2023年下期のインターネット利用環境に関する調査結果です。

news108.png

LINEで求職者に合った採用情報を配信 No Companyが「チャットボット for 採用マーケティング」を提供開始
就活生が身近に利用しているLINEを通して手軽に自社の採用情報を受け取れる環境を作れる。