Weitere ähnliche Inhalte
Ähnlich wie 良い?悪い?コードコメントの書き方 (20)
Kürzlich hochgeladen (11)
良い?悪い?コードコメントの書き方
- 5. コメントはどのように書かれるの?
プログラムの言語によって構文は様々
「ラインコメント」と「ブロックコメント」の2種類
Javaや
// これがラインコメント JavaやC++, C#など C#など
for (int i=0; i<65535; i++) {
ここから、 Javaに
/* ここから、ブロックコメント JavaにC/C++, C#など C#など
・・・・・・・・・・ここまで */
public static void main (String args[]) {
' VB系(VB6、VB.NET、VBA、VBScript)はこれ
VB系(VB6、VB.NET、VBA、VBScript)はこれ # これはシェルスクリプト
' ブロックコメントはないよ PerlやRubyも
# PerlやRubyも一緒
Private Sub Form1_Load() れはSQL
-- これはSQL
<!-- HTMLに -->
<!-- で囲むHTMLに -->
<%-- ASP、 --%>
<%-- で囲むASP、ASP.NET --%>
- 11. コメントはかくあるべき!
~方法ではなく理由を説明する
方法ではなく理由を
方法ではなく理由 説明する
コメントには、プログラムが処理を進めていく
具体的な方法を書くべきではありません。
→処理の方法や内容はコードを読めばわかる
処理内容の説明ではなく、
なぜそのように書かれているのか?
という理由や、
最終的に何が達成されるのか?
を説明する。
- 12. コメントはかくあるべき!
~方法ではなく理由を説明する
方法ではなく理由を
方法ではなく理由 説明する
× UserRegistryからのデータで
/* UserRegistryからのデータで
* Registryオブジェクトを更新する。
Registryオブジェクトを更新する。
オブジェクトを更新する
*/
ではなくて、
○ 登録情報を 参照できるように
/* 登録情報を後で参照できるように
キャッシュする。
* キャッシュする。
*/
と書く。コードの意図を説明していますよね?
- 13. コメントはかくあるべき!
~方法ではなく理由を説明する
方法ではなく理由を
方法ではなく理由 説明する
コメントを書くときは、どちらの種類のコメントを
書こうとしているのかを常にチェックする。
どちらも同じことだと考えられるけれど・・・
前者・・・単に内容がわかるだけ
後者・・・コードの意図が理解できる
と大きな違いがあるのです。
- 14. コメントはかくあるべき!
~方法ではなく理由を説明する
方法ではなく理由を
方法ではなく理由 説明する
保守によってコードに手を加える場合でも、
その修正によって
コードの存在理由が変化すること
は
その実現方法を変更すること
に比べれば少ない。
コメントに理由を記述した場合のほうが、
コメント自体の保守作業もずっと楽になる。
- 15. コメントはかくあるべき!
~方法ではなく理由を説明する
方法ではなく理由を
方法ではなく理由 説明する
コメントには
「方法の説明ではなく、理由の説明を書く。」
また、コメントには「特定の実装方法を選択した理由」を
書くことも考えらます。
あるコードの実装方法として2通りの選択肢があって、
その一方を採用した場合など、その選択の根拠を説明する
コメントがあると良いですね。
- 16. コメントはかくあるべき!
~コードの内容を言い換えただけの説明は避ける
コードの内容
コードの内容を えただけの説明
説明は
コードの内容をそのまま書いただけ。
× iをインクリメント
// iをインクリメント
i++;
「見たまんまやん!」
と言われそうなコメントは必要ありません。
「コードの内容を単に繰り返すだけの説明を書かない。」
- 17. コメントはかくあるべき!
~コメントをコードの代用にしない
コメントをコードの代用
コメントをコードの代用にしない
言語自体の機構で強制することが可能な制約
×
この変数 xxxクラス以外からアクセスしてはならない
変数に クラス以外
// この変数にxxxクラス以外からアクセスしてはならない
この条件を言語の具体的な構文で表現することを検討する。
→public変数を、よりスコープの狭い変数に変更する等
- 18. コメントはかくあるべき!
~コメントをコードの代用にしない
コメントをコードの代用
コメントをコードの代用にしない
次の点にも留意する。
コードを分割して、適当な名前の付いた複数の関数に分ける
→ロジックをよりわかりやすく表すことができる場合がある
変数の用途を説明するコメントを書いてはいけない
→そのコメントが必要なときは、変数名を適切なものに変更
自分がコードを説明するためのコメントを
たくさん書いていることに気付いたら、
とりあえず作業をやめる。
そして、先に解決する大きな問題がないかを考える。
- 19. コメントはかくあるべき!
つコメントを書
~役に立つコメントを書く
優れたコメントを書くには・・・
→コードの場合と同じで「見直し」と「修正」を
何度も繰り返しながら質を高める。
ではいったい、どのようなコメントが
「優れたコメント」
と言えるのでしょうか?
- 20. コメントはかくあるべき!
つコメントを書
~役に立つコメントを書く
読み手にとって意外なコードを説明するコメント
コード内に
特異な要素や通常は予期しない処理
読み手にとって意外に思われる記述
が含まれる場合、その部分を説明するコメントを書く。
コードを書いた本人でさえ忘れることが多いので、
あとになって「コメントを書いておいて良かった!」
と実感できます。
- 21. コメントはかくあるべき!
つコメントを書
~役に立つコメントを書く
正しい情報
コメントがコメントでないのはどんなとき?
それは「ウソ」が書いてあるときです。
真実ではない情報を謝ってコメント内に持ち込んで
しまうことは容易に発生し得る問題です。
コメントが記されているコードを修正するときに
とてもありがちなので注意!
- 22. コメントはかくあるべき!
つコメントを書
~役に立つコメントを書く
書く価値のあるコメント
混乱を招くようなコメント、ごく一部の人しか
理解できないコメントを書かない。
コメントはどこで誰に読まれるかわからない!
×
ここの仕様はオレの脳内にあるので直接聞いて!
仕様はオレの脳内にあるので直接聞いて
// ここの仕様はオレの脳内にあるので直接聞いて!
×
// これ直ってなくない? 後で直してもらうかも
これ直ってなくない?
- 23. コメントはかくあるべき!
つコメントを書
~役に立つコメントを書く
明瞭である
あいまいな記述は禁物。
可能な限り具体的で明確な内容を書くようにする。
読み手が「これはどういう意味?」と考えこんでしまう
ようなら、それはかえってコードの質を下げている!
×
とりあえず無限 無限ループでもしときます
// とりあえず無限ループでもしときます
while (true) {
- 24. コメントはかくあるべき!
つコメントを書
~役に立つコメントを書く
理解しやすい
読んで理解できるもの。
とくに略語等は読み手を混乱させることがある。
×
SGGKかどうかの
かどうかの判定
// 彼がSGGKかどうかの判定
×
FPMPの威力を測定する
// FPMPの威力を測定する
- 25. コメントはかくあるべき!
~コードの理解に不要な要素を排除する
コードの理解
コードの理解に不要な要素を排除する
コメントはその周囲のコードの理解を助けるもの
集中してコードを読むことを妨げるよう要素を
コメントとして書いてはいけません。
次のようなコメントは不要です。
- 26. コメントはかくあるべき!
つコメントを書
~役に立つコメントを書く
過去の情報
以前のコードで使用されていた処理方法の記録を
コメントとして残しておく必要はありません。
→バージョン管理システムに任せば良いこと
バージョン管理システムを有効に利用する。
- 27. コメントはかくあるべき!
つコメントを書
~役に立つコメントを書く
不要なコード
コードをコメントで囲んで無効化しておくこと。
混乱のもとになるので避ける。
- 28. コメントはかくあるべき!
つコメントを書
~役に立つコメントを書く
ASCIIアート
ASCIIアートの絵や図形などを使った方法でコードを
強調しようとすることを避ける。
× badExample(n, nyanco(matatabi));
// ^^^^^^
// 私のお気に入りの関数♪
のお気 りの関数♪
関数
エディタでプロポーショナルフォントを使用している
場合には、表示がずれるので意味がない。
- 31. 実際にコードを改善してみよう
さらに、
○ for (int i=0; i<recipes.size; ++i) {
printRecipe(recipes[i]);
}
と改善できます。
これならコメントがなくても理解できますね。
※ループ変数の「i」は変更されてないことに注意してください。
スコープ(有効範囲)が非常に小さいループ変数に名前をつけると、
かえってコードを読みにくくしてしまうからです。
- 33. コメント表記に関してきをつけること
~一貫性
一貫性
すべてのコメントの表記は明瞭であって、
一貫したものである必要がある。
→開発プロジェクトでスタイルが定めら
れている場合はそれに従うこと。
既存の優れたコードの記述を調べて、
そのスタイルに習うのも良い方法です。
- 34. コメント表記に関してきをつけること
明瞭なブロックコメント
~明瞭なブロックコメント
明瞭なブロックコメント
コメントがコードの間に割って入って、
ロジックの流れを断ち切ってはダメ。
× /*
複数行からなるコメント
からなるコメント。
複数行からなるコメント。
こんな書
こんな書き方だと
わかりづらいですね。
わかりづらいですね。
*/
○ /*
大量のコード
のコード内
* 大量のコード内にブロックコメントを
配置するときは このように書
するときは、
* 配置するときは、このように書いたほうが
格段に みやすくなる。
* 格段に読みやすくなる。
*/
- 35. コメント表記に関してきをつけること
~コメントのインデント
コメントのインデント
コメントがコードの間に割って入って、
ロジックの流れを断ち切ってはダメ。
× private void strangeCommentStyle() {
for (int i=n; i<JUST_ENOUGH_TIMES; i++) {
これは次 のコメント。位置がずれてて
// これは次の行のコメント。位置がずれてて分かりにくい がずれてて分
doSomethingMeaningful(i);
のこの行にあったらわかりにくい。
// 上のこの行にあったらわかりにくい。
anotherUsefulOperation(i);
}
}
- 36. コメント表記に関してきをつけること
保守の負担が いスタイルを選
~保守の負担が軽いスタイルを選ぶ
保守の負担が軽いスタイルを選ぶ
コードを書くための時間をコメントの手直しに消費
してしまうようなコメントは書かない。
×
/************************************************
* こんなコメントだと *
右側」
* 「右側」を直すのが *
たいへん・・・。
* たいへん・・・。見た目は綺麗だけれど・・・。 綺麗だけれど・・・
だけれど・・・。 *
************************************************/
- 37. コメント表記に関してきをつけること
~フラグ
フラグ
コメントはコード内にインラインのフラグとして
使用することができる。
マークして置くと、後からカンタンに検索をすることができる。
これは開発ツール(VisualStudioやEclipse)の機能として搭載さ
れているので積極的に活用する。
○ 初期化処理を追加する
する。
// TODO: 初期化処理を追加する。
不具合発生のため
のため、
// UNDONE: 不具合発生のため、現在対応中
// HACK: パフォーマンス改善する。
パフォーマンス改善する。
改善する
※Visual Studio(C#)のコメント・トークン例
TODO・・・未実装 / UNDONE・・・未完成/ HACK・・・要改変
参考:http://www.atmarkit.co.jp/fdotnet/dotnettips/163vsjump2/vsjump2.html
- 40. コメントを活用するための注意点
ルーチンを書
~ルーチンを書くためのコメント
ルーチンを書くためのコメント
先にルーチンの構造にしたがってコメントを書く場合
→コードを書き終えた時点で、最初に書いた各コメン
トがまだ有効かどうかを確認する
後でコメントを追加する場合
→適切なコメントを書く作業を忘れないようにする
理想的なのは・・・
コードを書きながら並行してコメントを書くこと
です。
- 41. コメントを活用するための注意点
バグの修正通知
~バグの修正通知
バグの修正通知
バグを修正したときに、そのことを通知するための
コメントを書くことが習慣的に広く使われますが・・・
→これは望ましい使い方ではない!
×
// 管理番号 B11840
blah.func()メソッドは処理が適切にできていなかったため
メソッドは処理
// blah.func()メソッドは処理が適切にできていなかったため
blah.func2()を使用するように変更した
するように変更
// blah.func2()を使用するように変更した
blah.func2();
このようなコメントは善意で書かれたものでも、
結果的に有益な効果よりも弊害をもたらすことが多い。
- 42. コメントを活用するための注意点
バグの修正通知
~バグの修正通知
バグの修正通知(つづき)
バグを本当に理解するために
→BTS(バグトラッキングシステム)でバグを検索、
修正前のリビジョンファイルを取得し調査する
等が必要になってしまう。
実際には、そのようにバグ修正が行われたことを
まったく知らなくても特に問題はなく、そのほうが
かえって効率的に作業を進められます。
- 43. コメントを活用するための注意点
バグの修正通知
~バグの修正通知
バグの修正通知(つづき)
このようなコメントをいったんつけ始めると、
開発の終盤や保守の段階に至った頃にはその数が
大幅に膨大しています。
賞味期限切れの情報
読み手のコードへの集中を妨げて、
主要な実行の流れを読み取りにくくするような情報
が、ソースコード中に散らばっているという状態に
なってしまう。
- 44. コメントを活用するための注意点
バグの修正通知
~バグの修正通知
バグの修正通知(つづき)
一見しただけでは気づきにくい修正を行った場合、
後でコードに手を加えようとするプログラムが再び
同じバグを作り出してしまうことを防ぐために
コメントを挿入すべきだという主張もあります。
しかし、そのような本当に説明が必要とされる
ごく限られた場合のコメントの使用は、
バグ修正の通知ではなく、むしろ「読み手にとって
意外なコードを説明する」ことを目的としたものと
考えるべきです。
- 45. コメントを活用するための注意点
コメントの劣化
~コメントの劣化
コメントの劣化
コメントは劣化します。
コメントに限らず、保守が行き届いていないコードは
劣化しやすく、放っておけば時と共に欠陥が増えます。
コメントの劣化は、コードのほかのどの要素よりも
ずっと急速に進み、その説明の対象であるコードと
同期されていない古いものになりがちです。
コードの変更時には、そのコードに付けられて
いるすべてのコメントを適切に更新する。
- 46. コメントを活用するための注意点
コメントの劣化
~コメントの劣化
コメントの劣化
コードブロックをコメントアウトしたまま残さない。
コメントアウトされているコード
未完成のまま放置されている修正コード?
作業がまだ進行中?
最終的にうまくいかなかった?
→そのコードを読む他のプログラマを混乱させる。
書いた本人でさえ、一定期間を過ぎたあとに見ると
意図のわかりにくいもの。
そのようなものがある場合、注釈を付けるか、
コードを完全に削除するべきです。
- 47. コメントを活用するための注意点
保守段階のコードの無意味なコメント
のコードの無意味
~保守段階のコードの無意味なコメント
保守段階のコードの無意味なコメント
保守段階においては、無意味なコメントを見つけて
も、それが危険なコードである場合以外は、削除せ
ずにそのままにしておく。
→それが危険なコードであるという情報になり、
将来の保守担当への警告となる。
事実として間違っているコメントや、誤解を招く
おそれがあるコメントは、コードの保守作業の一環
として適切に訂正をする。
- 48. コメントを活用するための注意点
保守段階のコードの無意味なコメント
のコードの無意味
~保守段階のコードの無意味なコメント
保守段階のコードの無意味なコメント
各種有用なコメントフラグの意味を理解して、
それらに対して十分に関心と注意を払う。
コメントアウトされたまま残っている出力ステート
メントにもきをつける。
→それは、過去にその周辺で問題が発生した
ことを示す確かな証拠!
常にコードを信じて、
コメントを疑うことを忘れないように!