アカウント名:
パスワード:
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
アレゲは一日にしてならず -- アレゲ研究家
コメント部分 (スコア:1)
doxygen などで出力するために詳しく書いていますから。
コメント行数 > 関数行数、なんてのも多数。
#この話題での行数ってステップカウント換算なのかしら?
コメントは重要なんだけど (スコア:3, 興味深い)
「実装にコメントを書くな」
なんて言う過激で衝撃的なお告げもあります。
JUnit 実践講座 - プログラミングスタイルガイド [morijp.com]
曰く、実装にコメントを書くと、
リファクタリングの妨げになるので、
書くならテストにコメントを書けと、、、
言いたい事は分るのだけど、
これをこのまま鵜呑みにして良い物かどうかは
判断し兼るところです、、、
確かにリファクタリングは楽になるんでしょうけど、
javadoc さえも書かない方が良いと言っているのはどうかと、、、
どうしても API ドキュメントのような物が必要な場合は、
なるべく開発工程のいちばん最後に書けと言うのですが、、、
# それはそれで面倒かつ効率悪い気が、、、(- -;;;)
私は頭が古いせいか、
テストコードを見ないと、詳細が分らないのは
流石にちょっと行き過ぎだろ!?と思えていけません、、、(- -;;;)
また、いくらリファクタリング優先とは言え
最低限、実装読解の助けとなるコメント
(参考文献、アルゴリズムやデータ構造等の名称等)は
実装側に必要なんじゃないかと思うんですよね、、、
実装とドキュメントを分離するのは管理コストが増えるからこそ
javadoc のような物を有難く思えるわけだし、、、
まぁ馬鹿正直に全て受け入れる事もないんでしょうけど、
XPやってる方々の率直な意見も聞いてみたいところです、、、
uxi
Re:コメントは重要なんだけど (スコア:0)
> 流石にちょっと行き過ぎだろ!?と思えていけません、、、(- -;;;)
詳細をむやみに分からせないためでもあるんだけど。
> 最低限、実装読解の助けとなるコメント
> (参考文献、アルゴリズムやデータ構造等の名称等)は
> 実装側に必要なんじゃないかと思うんですよね、、、
そういう宣言的なコメントならいいんだけど、
動作を記述したコメントは有害なんだよね
Re:コメント部分 (スコア:0)
Re:コメント部分 (スコア:2, すばらしい洞察)
Re:コメント部分 (スコア:0)
C/C++の場合、ヘッダファイルとソース、コメントはどっちに書きますか?
ヘッダを見る利用者のためにヘッダに書くべきだ、という意見もわかるし、ヘッダの見通しが悪くなると全体が把握しづらくなるのでソースに書くべきだっていうのも同意できる。doxygenなんかは、ヘッダに短いコメント、ソースに詳細なコメントなんかをサポートしててそれは前者と後者を両立させてるとは思うんだけど、同じような内容を二度書くのはちょっと面倒だし、修正したときに片方のコメントの修正を忘れることもしばしば・・・。
なんかいい指針ないかな?
Re:コメント部分 (スコア:2, 興味深い)
昔からの指針だと思います。実装についてのコメントは実装本体へ、
利用者向けのドキュメントは別ファイルへ。
Re:コメント部分 (スコア:0)
そういう視点で考えるとヘッダとソース以外にも、基本クラスはヘッダ寄りに、派生クラスではソース寄りにコメントを配置するとか考えられてすっきりしますね。
レスしてくれたお二方どうもありがとう!
Re:コメント部分 (スコア:0)
本体には実装に関する最低限のコメントだけ書けよ
Re:コメント部分 (スコア:0)
実装部分に書くのはhow
客に書いて欲しいが書いてくれないのがwhy