プログラマーが知るべき「良いコメント」の条件【第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
-
製品資料
“攻撃者優位”なサイバーセキュリティ、全ての「穴」をふさぐ方法とは？ -
製品資料
実際に悪用される脆弱性は4％前後 優先的に対処すべき脆弱性を把握するには？ -
製品資料
HubSpotの機能を拡張する法人データ活用法 -
製品資料
面倒で非生産的な「名寄せ」作業 高精度＆高効率に実施するには？ -
製品資料
名刺管理には「その先」がある 成果のでない営業活動から脱却する秘訣
こんなメディアも見られています
TechTargetジャパンに関連する情報をお探しであれば、こちらのメディアもお役に立てるかもしれません。
ベンダーコンテンツ PR
From Informa TechTarget
SpecialPR
アクセスランキング
-
1
Netflixのバックエンドは「ほぼJava」 3000超のアプリを支える開発基盤の裏側
-
2
ISMSの“コンサル丸投げ”が招く数千万円の無駄 NTTドコモビジネスの脱出劇
-
3
「Microsoft 365」が乗っ取られる 跡形もなくMFAを破る手口
-
4
「WSUS」終了の時限爆弾 “本命”移行先ツールとMicrosoft提唱の新管理手法
-
5
「結局使わなくなる」Microsoft 365 Copilotを半年で定着 キリンの3施策
-
6
100億円の「Linux更新」を回避 みずほ銀行が選んだ“おきて破り”のRHEL延命策
-
7
IT製品の導入に関するアンケート「サーバ＆ストレージ」編
-
8
「企業におけるAIの運用」に関するアンケート
-
9
「OSの選定・導入」に関するアンケート
-
10
アラート47％削減 オープンハウスが捨てた「全部メール通知」の監視体制
ホワイトペーパーランキング PR
-
1
AIエージェントで多様な日常業務を効率化するための入門ガイド
-
2
財務・会計はAI活用でどう変わる？ 調査で見えた変革の道筋
-
3
AIが「わざわざ使うツール」になっていない？ 業務で自然に使う導線にする秘訣
-
4
JR西日本ITソリューションズが「監視業務の属人化」を解消した方法とは？
-
5
「脱Excel」か「Excel快適化」か？ 現場にやさしい業務改善の進め方
-
6
「結局、一部の人しか使わない」 AI活用が業務に定着しない根本的な理由
-
7
コスト分析で見る「デバイス復旧」の代償 損失額から導きだされた投資戦略とは
-
8
Macの安全神話は崩壊？ 最新の脅威動向から見えた攻撃のトレンドと有効な対策
-
9
ゼロトラストにおける「IDaaSの課題」と補完すべき重要機能とは？
-
10
「NAS」「SAN」「DAS」は何が違う？ いまさら聞けないストレージの基礎
TechTargetジャパン SNS
@techtarget_itmをフォロー
インフォメーション
注目情報をチェック
TechTargetジャパンをフォロー