skillup

技術ブログ

プログラミング全般

コメントについて

投稿日:2016年7月1日 更新日:

リーダブルコード 第5・6章はコメントについて。

今回はコメントです。ここは結構賛否両論になるところではないかと思います。

ざっくり分けると「できるだけコメントは詳しく書くこと」という意見と「コメントはなるべくかかない(コメントを書く必要がないくらいコード自体をわかりやすくしろ)」という意見が多いですね。もちろん一番大切なのはバランスなんですが・・・

リーダブルコードでは両方の立場(書くべきでないコメントと書くべきコメント)からの意見が書かれています。

目的は読み手が理解しやすいかいなか

そもそもコメントの目的としては読み手にとって読みやすい、書き手に誤解されない、ということが重要です。コメント自体はこれを実現するための手段になります。

なんでもかんでもコメントを書いていると、コードが長くなり、コードを読む行為が増えますので、その分だけ読み手に負担をかけます。

逆に少なすぎれば当然、情報を得るのに必要な時間・労力を読み手に与えることになります。

読み手の立場に立って考えることが大切になってくるわけです。

当たり前のことをコメントにかかない

例えばコンストラクタにこれはコンストラクタ、みたいなコメントですね。読めばわかるようなことはわざわざコメントしないということですね。

コメントが冗長になりすぎる場合は命名変更を考える

コメントが冗長になりすぎる場合はコメントを減らすことになりますが、まずは命名を変えられないか、と考えてみましょう。要はコメントではなく、名前から情報を伝えようということです。

考えの記録を書く

コードを書くときの大切な考えを記録しておきます。

映画監督のコメントのように → 注意しておきたい情報や気づきなど

コードの欠陥 → あとあと必要な修正や問題点など

読み手がはまりそうなポイントを書く

間違えやすいことや起きやすいバグなどについて。通常だったらAという方法をとるのになぜわざわざAじゃない方法をとっているのか、など。

全体像を説明する

クラスの一番上や大きなメソッドには箇条書きだったり、全体として何をするべきものかというのを要約しておきましょう。

簡潔かつ、わかりやすいもの

これはコードと同じなのですが、同じ情報量だったら簡潔なもののほうがよいです。なるべく短くできないか、文書よりは式や記号的なもので代用できないかを考えましょう。

意味不明な代名詞を使わない

あれ、これ、それ、どれといった何を指すのかがわからないものは読み手に混乱を与えるのでやめましょう。

具体性のあるコメントにする

コードと同じなのですが、意味がぼやけていて、解釈の仕方がわかれるようなものではなく、具体性のある記述にしましょう。

実例を書く

メソッドのコメントなどは言葉で説明するより、具体例で説明したほうがわかりやすいでしょう。

-プログラミング全般
-

執筆者:


comment

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

関連記事

no image

オブジェクト指向設計 ダックタイピング

オブジェクト指向シリーズ。ダックタイピング・・読む前は名前は聞いたことあるような気がする・・程度で細かいことは何一つわからない状態でした。今回具体的なコード例があった分イメージを何とかつかむことはでき …

no image

ExcelVBAでの他のアプリの起動

2日続けてExcelVBA。 やはり細かく分けてすぐにプロシージャごとにテストできるのはものすごく大きなメリットですね。本日は別のアプリ起動と操作に関して。 自分がやったことはWordとメモを起動して …

no image

プログラミングを習得するときに必要な2つの大事なこと

元々私は塾で仕事をしていましたが、いろいろ紆余曲折ありましていまではWEBエンジニアとして仕事をしております。 エンジニアとしてのキャリアは3年ぐらいなので正直あまりないのですが、開発者と平行してプロ …

no image

例外・エラーに関する考察

えー今現在、設計の仕事をしていますが、今までいい加減だったエラーの処理を見直すいいきっかけになってます。 半年前にも同じような記事書いてますねー。苦手意識は変わらないようです・・(汗) 例外処理に関し …

no image

業務フローの分解について

上流工程を担当するようになり、プロジェクトマネジメントや、要件定義、業務フロー分解などについて勉強しておいたほうがいいなーと思い、最近では読書をしております。 本日読んでわかりやすかった本は「はじめよ …