So-net無料ブログ作成
検索選択

ソースコードのコメントについてちょっとしみる事がかいてあった [システム開発]

アンドリュー・ハントとデビッド・トーマスの名著「達人プログラマー」に、ソースコードのコメントに関する記述があったのだがしみる内容だったのでメモ

達人プログラマー―システム開発の職人から名匠への道

達人プログラマー―システム開発の職人から名匠への道

以下P.253からの抜粋
 一般的にコメントは「何故」それを行うかという目的やゴールを記述すべきです。既にコードが「どのように」それを行うかということを表しているため、コメントでそれを記述するのは無駄な事であり、DRY原則に違反する行為となるものです。

 ソースコードへのコメントは、技術上のトレード・オフ、意思決定の理由、却下された代替え案、といったようなプロジェクト資料のどこにも記述されない難解なポイントを記述する為のものなのです。

 これはクラスや関数ヘッダーに書かれるような機能概要ではなく、ソースコード中に埋め込まれるコメントについて記載されたものだ。
 新人の頃はどんな内容をコメントとして残すのかよく悩んだものだ。今では感覚的にどんなコメントを残す/または残さないかはわかったつもりだが、人にアドバイスをする時にもやもやとした思いをうまく表現できずに困ったこががある。
 内部的にもやもやとしていた点について、明快で適切なコメント記述のデジタル表現を見つける事ができた為、あとはこの内容を適切に伝えられれば後ろを歩く人から白い目でみられることもなくなるだろう。

 新人の頃は仕様通りの内容をどうやってソースコードに落とし込むかが本人にとっての問題領域であった為、ソースコードの内容をそのままコメントとして残すことがしばしばあった。
 例えば、初めて調べた言語の機能やライブラリのリファレンスの内容などだ。これらは知らないプログラマーには多少役に立つかもしれないが既知のプログラマーにとっては邪魔ものでしかなく、知らないプログラマーもリファレンスを見ればわかる事である。少なくとも未来の自分にとってもあまり役に立たないものだ。
#ただ、新人のころは普通のプロがラマーが書かないコードを常に書いているものなので、処理したい内容を書いておいてくれれば、後に適切にリファクタリングする為に役に立つ可能性はある. . .

 コメントとして残すべき内容は、「プログラマーは通常なら違う書き方がをするが、あえて別の書き方をした」とか「記述方法や処理方法にいくつか選択肢がある場合にあえてその方法を選択した理由」などだ。
 私が記述して役に立ったと思う内容はSQLのパフォーマンスチューニングの内容だ。たとえばJOINや大規模なSQLの一発発行をさけてあえて複数回に分けた場合や、Where句に記載すればSQLでフィルタリング可能なのにあえてコードで判別した場合などだ。
 適切なテストケースやデータに対して複数の処理方法を試し、パフォーマンステストの結果該当のコードを選択している場合が多いが、こういったコードにコメントがないと後のメンテナーはコードの内容に対して疑問を持ち、下手するとリファクタリングと称してデチューンされる可能性がある。
 逆にコメントがなかった為に自らデチューンしてお客さんに迷惑をかけた事もある。(自分ではコードを短くしてリファクタリングしたつもりだったのだが. . .)

 要するに「[あえて]こういったコードを書いた」場合に「[なぜ]こういったコードを書いた」のかをコメントとして残しておくと有用なわけだ。

 本書の著者が伝えたい内容はもっと多義にわたるが、あえて外れたところで感心してしまったので紹介がてらメモしておきました。
nice!(0)  コメント(0)  トラックバック(0) 

nice! 0

コメント 0

コメントの受付は締め切りました

トラックバック 0

この記事のトラックバックURL:
※言及リンクのないトラックバックは受信されません。
メッセージを送る
RSS RSS

この広告は前回の更新から一定期間経過したブログに表示されています。更新すると自動で解除されます。

×

この広告は1年以上新しい記事の更新がないブログに表示されております。