プログラマーが知るべき「良いコメント」の条件【第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
-
製品資料
[株式会社MatrixFlow] 「物流リソース最適化」ガイド：人員・配車・傭車を出庫依頼の確定前に決めきる -
製品資料
[株式会社キーエンス] なぜRPA導入は頓挫する？ シナリオ作成の壁を乗り越える解決策とは -
製品資料
[株式会社セールスフォース・ジャパン] 「CRMは設計と無関係」は本当か？ PLMとの融合で実現する高速開発 -
事例
[日本ヒューレット・パッカード合同会社] AIエージェントの時代にどう備える？ 「新たな働き手」を支える3要素とは -
製品資料
[日本ヒューレット・パッカード合同会社] “横並びの自動化”から脱却、AI活用で生産性と競争力を高める秘訣
こんなメディアも見られています
TechTargetジャパンに関連する情報をお探しであれば、こちらのメディアもお役に立てるかもしれません。
ベンダーコンテンツ PR
From Informa TechTarget
SpecialPR
アクセスランキング
-
1
なぜ「全社配布Copilot」は使われないのか？ 失敗に学ぶAI定着
-
2
法務と開発者で「言葉が通じない」問題 トヨタやソニーが語るOSS管理の真実
-
3
なぜ「Gemini 4 Argon」は出遅れたのか？ Googleが狙う“逆転のシナリオ”
-
4
損保ジャパンはなぜ「COBOL」を捨てなかったのか？ 脱メインフレームの真相
-
5
情シスの約8割が転職や退職を意識 調査で分かった“辞めたくなる最大の理由”
-
6
ChatGPTは“検索しまくり”でGeminiは“淡泊”？ データが明かすAIの裏側
-
7
情報漏えいはなぜ繰り返されるのか 今すぐ見直すべき「境界」
-
8
「Wi-Fi 7」経由でWindowsが乗っ取られる？ 最高権限奪取の恐怖
-
9
「結局使わなくなる」Microsoft 365 Copilotを半年で定着 キリンの3施策
-
10
「中堅・中小企業のネットワーク・セキュリティ運用実態」に関するアンケート
ホワイトペーパーランキング PR
-
1
不審メールの経路や見せ方に変化？ 2026年夏の3事例から見えた動向と対処方法
-
2
家庭用Wi-Fiルーターの業務利用は危険？ 避けるべき理由と具体的な対策
-
3
Microsoft 365を安全に運用 うっかりミスやサイバー攻撃に備えるデータ保護術
-
4
財務部門がAIを最大限に活用する方法 無駄のない戦略的リーダーシップへの道
-
5
LLMが兵器化？ 元FBI高官が鳴らす警鐘とセキュリティツール統合のポイント
-
6
「オンプレミス回帰」せざるを得ない“合理的な理由”
-
7
なぜRPA導入は頓挫する？ シナリオ作成の壁を乗り越える解決策とは
-
8
生成AIを開発に導入しても効果が見えない？ 実証実験で分かった成果と課題
-
9
経産省DX指針から読み解く、受発注業務デジタル化ロードマップ
-
10
HDDを使わない「SSDオンリー」が無謀なのはなぜ？
TechTargetジャパン SNS
@techtarget_itmをフォロー
インフォメーション
注目情報をチェック
TechTargetジャパンをフォロー