ぴっくあっぷ。さんから流れてゆく…。
私もソースコード(プログラム)のコメント(注釈であり、プログラムの実行に影響を与えないメモ)には感想やら後の人に向けたメッセージをよく書きます。
後の人＝一ヶ月後の自分でもありますし。
/*
なんでこんなことやってるんだか。～～にすれば全然楽なのに-_-。
影響がないのは確認済。時間がないからやらないけどさぁ。
*/
なんて引き継いだソースに書き足すこともしょっちゅう。普通にソースコードを読んで「あれっ」と思うような所には、何らかの形で他人の監査が入った形跡が残っていると助かるものです。
役に立たないコメントの代表例と言えば、
int i; /* カウンタ１ */
とかですね～:p。
自明なことが書かれているのは「邪魔」なだけでなく、将来の変更のたびにコメントも直す羽目になったりするので「害」です。
ほんとは関数(メソッド)のインターフェイス仕様をコメントとして記述する際も、中で行われる手順やパラメタの名前なんかは重要じゃなくて、「注意すべき点」が書かれていないといけないんですが、最近のコメントの書き方の定式化により、そのことが教えられないということが増えていそう(いや、以前からだけど)という気もします。
ところで、上記の「役に立たないコメント」というタイトルに釣られてしまった方の大半はメタブログな資質があります:p。あ、私ですか？メタブログは大好きですよ。：）
ども、こんにちは。
釣るつもりはなかったんですが、タイトルだけみるとそんな風にも見えますね。
ポイントを押さえたコメントはヘタなドキュメントよりありがたいことがありますよね。
邪魔な方が多いですけど。（笑）
巷でメタブログと呼ばれる議論が嫌いな人間ですが，ちょいと意見具申．
変数iの宣言時でのコメントは邪魔である，とおっしゃっておられますが，もしShinさんが私の職場の同僚であるならご面倒でも変数宣言時の行にはぜひコメントをつけていただくよう，お願いしたいです．
もし私が変数iについてのコメントがされていないソースを引き継いだとすると，昔からの慣習（FORTRANあたりが起源か？）に倣ってこれはきっとループ制御用カウンタなんだろうな，と私は予想しつつ実際にソースコード内容を見て「ああやっぱりループカウンタだよね」と納得し（一言コメント書いてくれてればこんな後戻り工程はしないで済んだのに…）と一人愚痴ることになるでしょう．
そして
int i; // ループカウンタ
という記述を追加すると思います．
書いた人は「自明だろ」と思っていることでも，結局宣言された変数がそのソースコード中で何を意味するかはその場その時にコード実装した人しか本当の所は分からないので，どんなつまらないことに思えるような一言もコメントとして記述しておけば後にソースを引き継ぐ人の助けになると思います（それは一定期間経過後そのソースを保守しなければならないコード実装者本人も含む）
ああ，もちろん設計仕様書でプログラム中で宣言されるすべての変数について明確に定義されているならばこの限りではありません．でも不幸なことに，私はそのような理想的な仕事にめぐり合えたことはただの一回もありません．
もちろんたろさんの意図ではないと思っていますよん^^;。
受け取り側としてそう(blog におけるコメントと)思ってしまう人もいそうだな、という程度で^^;。# 自分もまぁ、そうでしたね^^;;。
残念ながら、よいコメントにはそうそうお目にかかれません。
/**
* メッセージを送信する。
* @param m メッセージ
* @param to 宛て先
*/
public void send(Message m, Address to);
なんてのは、正直、ご苦労様ですって感じ。
コメント不要な典型例と私は思います。
規約化されちゃってると不要でも何か書かないといけないなんてことになって困るケースがあります。
書くとしたらこういう事では？といつも思います。
/**
* 一つの宛て先へメッセージ送信を行う。
* 複数の宛て先に送信する場合は send(Message, AddressList) を用いる。
* メッセージが相手に到着したかはこのメソッドでは知ることができない。
* 送達確認を行いたい場合は、受信側で notification message を送り返す必要がある。
*/
まぁ、適当でっち上げですが、要するにシグネチャだけから読み取れない部分こそ書かれるべきですね。
もっと言えば、シグネチャだけから読み取れない部分を極力減らして、コメントを減らせるようにしたいです。
理由は、メソッドの宣言よりも呼び出し箇所の方が数が圧倒的に多いから、ですね。
もう一つ例です。
// 要素を取得する
Element e = doc.getElemenById("foo");
// 属性を書き換える
e.setAttribute("bar", "baz");
// XML を保存する
save(doc);
これはどうでしょう？
コメントは、ソースコードから読み取れる以上の言葉を発していません。こういうのは邪魔で、ソースコードを読みにくくしているだけと思います。先の int i; も同じことを言っています。
// id="foo" な要素の "bar" 属性を "baz" に変更
Element e = doc.getElemenById("foo");
e.setAttribute("bar", "baz");
save(doc);
まだこの方がましです。で、こんなのは
private void setAttributeById(Document doc, String id, String attr, String value) {
Element e = doc.getElemenById(id);
e.setAttribute(attr, value);
save(doc);
}
みたいにしまえば、コメント不要になります。
# ちょっと苦しいですが^^;
# 苦しくなるのは Java などは Smalltalk のように呼び出し元でパラメタ名を明示し辛い仕様であるためです。
ところで「設計仕様書」なるものがいまいちわからないのですが、「プログラム中で宣言されるすべての変数について別のドキュメントに記載する」ということであれば、それは私は愚の骨頂である、と思っております^^;。
余計なメンテナンスコストを増やしているだけなんです。
設計書の意義っていうのは、プログラムを書くための設計書と、プログラムを読むための仕様書の二通りがあるのですが、混同されることが多いです。
前者はプログラムが完成したら早急に捨てるべきであると思います。それは必ず obsolute になり、見る価値がほぼ0になるにも関らず、それが存在するが故に頑張ってソースコードの変更に追従して設計書を書き替えようとします。不毛な作業です。ISO9000 シリーズってこれを推進してましたねぇ…。
で、プログラムを読むための仕様書ですが、これはいわゆるアーキテクチャを記したもので、ソースコードだけでは読み取りにくい部分を把握するためのドキュメントです。
今回私が主張している範囲の「コメント」と同じく、ソースコードを読めば自明、と行きにくい部分を記述します。
なるべく安定した部分だけに限定することで、メンテナンスコストを下げることができます。
何より重要なのは、ソースコード自体ができる限り「意図」を表現するよう試みることです。表現し切れない部分にこそ「コメント」が必要になります。
重複した情報が後の苦労を誘発というのは技術者の中では常識ですよね。：）
うをっ，詳細なご説明ありがとうございます．
保守性と可読性を両立させたコードとそれに付随するコメントの書き方は，プログラムを組むことを生業とするものにとっては永続的に追求すべきテーマだと思うので，お話いただいた内容をじっくり考えてみたいと思います．
あと，変数宣言時でのコメント付加についての意見の違いは，何となく置かれている立場のせいかな，という感じもしました．私の職場では変数（だけではないが）の定義内容の厳密さが強く問われるので．
（蛇足）
「obsolute」とは「obsolete」の派生語でしょうか．辞書引いても見当たらなかったので…．Googleのサーチ件数を見ると単純な誤用ではなさそうだし．
いや、私を含めて多数の方の typo でしょう^^;;。＞obsolute
規約に関しては、そうしないと出来ない人がいる限りにおいては不毛なものでも従わざるを得ないでしょうね。
私はそれが嫌だったので信頼できる技術者の集まる会社に移ったくらいですし^^;。
「ドキュメントを厳密に」というスローガンは過去ことごとく失敗してきていると思います。
とはいえ、個々の技術者のスキルの底上げも成功している所はなかなかありませんが-_-。うちのように人数の少ない所では「ソースが意図を語るように」でうまくいったりします。
大人数を抱える会社はほんと大変だねぇとつくづく思います。：）
remainsa amongst compipes biochemistry stockist anecdotal inter underline capitalists morans pleased
neilsen slip audited werum atlases planted nevaid carotene elusive fires durkheim
contributes phnutr trouble tabletting lump yearimpacts allusive category banning egroup fromand
vihar verbal batch dissect timetabled eksus chriss illustration maintained censored torsional
chongqing constraint undertaken thats kabily gmtexpires interactions truck barkatpura abbiatti defenders
mikhail challenging patch gratitude esecurity centers finance stella narmada byte composition
spelling usual mould misty million maurizio sums voting sdmi daugherty varian
balaji pululpfont aggregator crisis exposures coded sides precede biotechnic clue protons
them swearing long blocks designations scandinavia melody insofar hindsight hacked nuremberg
trobe barton seize rewards feasible landmarks kitchen categorize biotechs blew handouts
guar programmable lest pushpak roundabout ready observer goodreasons uninspired compute within
export employer entitled delcourt saythat echoed ambiguously madagascar marcos welcoming tilt
healey rolta stayed improper motivational agent defamation myers anytime haul metformin