プログラマーが知るべき「良いコメント」の条件【第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
-
事例
[サイボウズ株式会社] DXに必要な「Dスキル」「Xスキル」を持った人材を育成するには？ -
市場調査・トレンド
[サイボウズ株式会社] データで見る、DXが「順調に進む企業」と「つまずく企業」の違い -
製品資料
[サイボウズ株式会社] 賛否が割れがちな「Notesからの移行」 新環境への移行を納得してもらうには？ -
事例
[ServiceNow Japan合同会社] 農林中金に学ぶ内製開発 処理効率を約2倍に高めAI活用も加速させた方法とは？ -
事例
[ServiceNow Japan合同会社] NTTグループのデジタル変革術、17万人が利用する決裁プロセス刷新の全貌
こんなメディアも見られています
TechTargetジャパンに関連する情報をお探しであれば、こちらのメディアもお役に立てるかもしれません。
ベンダーコンテンツ PR
From Informa TechTarget
SpecialPR
アクセスランキング
-
1
「データストレージの活用方法」に関するアンケート
-
2
【基本情報技術者試験】「デュプレックスシステム」と「デュアルシステム」の違いは？
-
3
「AI活用を前提とした業務PCへの移行」に関するアンケート
-
4
「VMware離れ」は本当か 3000社がVCF 9にかじを切った現実的な理由
-
5
100億円の「Linux更新」を回避 みずほ銀行が選んだ“おきて破り”のRHEL延命策
-
6
kintoneで実践 製造業のための「見積もり管理」改善のヒント
-
7
「Microsoft 365」が乗っ取られる 跡形もなくMFAを破る手口
-
8
Microsoft製品でここまで自動化できる 情シスがやめられる手作業10選
-
9
Oracle巨大ITプロジェクトはなぜつまずいたのか 8年で導入1割、追加で170億ドル
-
10
DXを阻む「動くだけ」のレガシーシステムに決別するための生成AI活用術
ホワイトペーパーランキング PR
-
1
生成AIのハルシネーションを防止 回答精度を高めるセマンティックレイヤーとは
-
2
AIエージェントで多様な日常業務を効率化するための入門ガイド
-
3
5回聞くだけじゃ足りない？ トヨタ式「なぜなぜ分析」の正しい実践方法
-
4
AIが「わざわざ使うツール」になっていない？ 業務で自然に使う導線にする秘訣
-
5
JR西日本ITソリューションズが「監視業務の属人化」を解消した方法とは？
-
6
「脱Excel」か「Excel快適化」か？ 現場にやさしい業務改善の進め方
-
7
インシデント対応工数を約3割削減、東京ガスの事例に学ぶ監視体制刷新のコツ
-
8
マンガで解説：「ゼロトラスト」「SASE」の必要性とメリット
-
9
5分で分かる「セキュア大容量ファイル転送サービス」の機能とメリット
-
10
情報セキュリティ対策早分かりガイド：25の自社診断で弱点と解決策を理解
TechTargetジャパン SNS
@techtarget_itmをフォロー
インフォメーション
注目情報をチェック
TechTargetジャパンをフォロー