プログラマーが知るべき「良いコメント」の条件【第4回】
Pythonソースコードの実例で分かる「本当に良いコメント」の書き方とは？
ソースコードに対する理解を補助するのが、適切なコメントだ。コメントを書くためにプログラマーが理解しておくべき原則を、実例とともに解説する。
プログラマーはソースコード内に、補助的なテキストを「コメント」として挿入可能だ。読みやすく、メンテナンスしやすいソースコードにするには「良いコメント」が欠かせない。具体的には、どのようなコメントが良いコメントなのか。
「本当に良いコメント」のPython実例はこれだ
併せて読みたいお薦め記事
連載：プログラマーが知るべき「良いコメント」の条件
- 第1回：「コメント」の“本当の意味”を誤解していないか？
- 第2回：Pythonのソースコードで考える「こんなコメントは無駄なだけで無意味」
- 第3回：「良いコメント」って結局何？ 「悪いコメント」に隠れた“深刻な問題”とは？
ソースコードの書き方
ソースコードの内容をそのまま繰り返すだけのコメントは、有益な情報をほとんど提供しない。良いコメントとは、読んだ人が「プログラム実行時に何が起こるのかを理解できる」コメントだ。
良いコメントの例を見てみよう。以下は、プログラミング言語「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エンジニアの問題解決に役立つ情報を厳選してお届けします。
Copyright © ITmedia, Inc. All Rights Reserved.
TechTarget発 エンジニア虎の巻
米国TechTargetの豊富な記事の中から、開発のノウハウや技術知識など、ITエンジニアの問題解決に役立つ情報を厳選してお届けします。
この記事の著者
関連記事
新着ホワイトペーパー PR
-
事例
[フォーティネットジャパン合同会社] 複雑化しがちな「SASE運用」 IT・医療・金融などの事例に見る導入成功の秘訣 -
製品資料
[フォーティネットジャパン合同会社] 「SD-WAN」導入で失敗しないための5つの重要事項 -
技術文書・技術解説
[フォーティネットジャパン合同会社] VPNの代替候補「ZTNA」を理解できるようになる“3大要素”とは？ -
事例
[フォーティネットジャパン合同会社] すぐ分かる「SD-WAN」選定のポイント 成功企業はどんな成果を出した？ -
製品資料
[SCSK株式会社] 「Dropbox」管理・運用の困りごと解決ガイド
こんなメディアも見られています
TechTargetジャパンに関連する情報をお探しであれば、こちらのメディアもお役に立てるかもしれません。
ベンダーコンテンツ PR
From Informa TechTarget
SpecialPR
アクセスランキング
-
1
半数がブルーカラー転向を視野に？ ベテランエンジニアを追い込む“54歳の壁”
-
2
PHP脆弱性「PHP2Shell」で2260万件に影響 情シスの緊急チェックリスト
-
3
みずほ証券が「液冷サーバ」を採用 1日3.6億件の計算を支えるための要件
-
4
「Microsoft 365」が乗っ取られる MFAを破る“本物の画面”の恐怖
-
5
「Windows」の不要なファイルを安全に消して容量を空ける方法
-
6
Microsoft月例パッチ1400件超で過去最多 「限界点」を迎えたパッチ管理
-
7
損保ジャパンはなぜ「COBOL」を捨てなかったのか？ 脱メインフレームの真相
-
8
RAGで「データをAIに送る」運用が限界を迎えている理由
-
9
SAP導入後も残る“Excel依存” 京急電鉄は「kintone」でどう解消した？
-
10
なぜ「Gemini 4 Argon」は出遅れたのか？ Googleが狙う“逆転のシナリオ”
ホワイトペーパーランキング PR
-
1
AI駆動攻撃にどう対抗する？ 超速の攻撃からエンドポイントを保護する方法
-
2
2026年のサイバーセキュリティには何が必要か？ 最新データに学ぶ傾向と対策
-
3
経験豊富な即戦力人材に直接アプローチできる、「攻めの採用」への転換術
-
4
「IT史に名を残すシステム障害」8選
-
5
最速72分でデータが流出？ 最新の脅威トレンドや侵入手法から分かった防衛策
-
6
AI駆動開発のスピードと安全性を両立 「品質・セキュリティ管理」の実践ガイド
-
7
不審メールの経路や見せ方に変化？ 2026年夏の3事例から見えた動向と対処方法
-
8
HDDを使わない「SSDオンリー」が無謀なのはなぜ？
-
9
「標的型攻撃メール」事例・サンプル集
-
10
Microsoft 365のメールセキュリティ、3つの“死角”と追加で検討すべき対策とは
TechTargetジャパン SNS
@techtarget_itmをフォロー
インフォメーション
注目情報をチェック
TechTargetジャパンをフォロー