プログラマーが知るべき「良いコメント」の条件【第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エンジニアの問題解決に役立つ情報を厳選してお届けします。
この記事の著者
関連記事
こんなメディアも見られています
TechTargetジャパンに関連する情報をお探しであれば、こちらのメディアもお役に立てるかもしれません。
ベンダーコンテンツ PR
From Informa TechTarget
SpecialPR
アクセスランキング
-
1
急増する「AIはこう言ってる」マン 判断を狂わせる「AI忖度」を防ぐには？
-
2
取手市がVDIと決別した理由 更改費用「4倍超」を約1.7倍に圧縮
-
3
「Excel至上主義」の終わらせ方 丸2日の手作業地獄から情シスと現場を救うには
-
4
221人調査で分かった「情シス最大のストレス」は？
-
5
「データストレージの活用方法」に関するアンケート
-
6
「AI時代の統合基盤・エンタープライズAI管理」に関するアンケート
-
7
自宅のWi-Fiが「遅い」「途切れる」本当の原因は？ Dellが推奨する鉄則
-
8
本当に安いPCで十分か？ “すぐ重くなる”を防ぐノートPC選びの絶対条件
-
9
100億円の「Linux更新」を回避 みずほ銀行が選んだ“おきて破り”のRHEL延命策
-
10
Claudeの不可視透かしに批判殺到 著作権消失や誤判定に潜む企業リスク
ホワイトペーパーランキング PR
-
1
年収2000万「クラウドセキュリティのプロ」になれる資格とは
-
2
セキュリティソフトをすり抜ける標的型攻撃メール、不審メールの見破り方とは？
-
3
Windows Updateの通信集中で回線が逼迫、ネットワーク刷新事例に学ぶ解決策
-
4
財務を戦略的組織へ進化させるAI活用術、4つの主要な障壁と解消方法
-
5
「NAS」「SAN」「DAS」は何が違う？ いまさら聞けないストレージの基礎
-
6
“あのファイル転送”で暗躍するノーウェアランサム
-
7
標的型攻撃メールを見破るには？ サンプル文面を例に傾向を解説
-
8
商用利用の安全性を確保し大量のコンテンツを高速で生成する、AI活用の秘訣
-
9
マンガで解説、1日で生成AI環境を構築できるワークショップの中身とは？
-
10
Dark AIが台頭する時代の新発想、「より高度なAIで対抗する」具体的方法とは？
TechTargetジャパン SNS
@techtarget_itmをフォロー
インフォメーション
注目情報をチェック
TechTargetジャパンをフォロー