アカウント名:
パスワード:
> そうですよね。なぜこのロジックを選択するに至ったか、もっとシンプルと> 思われる手法ではなにが問題だったかは長くなっても書いておくべきだと思います。
こういうことはコメントに書いてすませるべきではないですね。プログラム(マ)だけの問題ではありませんから、きちんと周知しレビューすべきです。
> コメントが必要ないのが綺麗なコードなんていうのは80年代で終わってますから。
80年代で終わっているのは君のおつむのほうで。
"表現の範囲は把握しておく"というサブジェクトに"すば洞"あげたいところです^^;
> 問題点はドキュメントに整理し、コメントはそこへのポインタを示すにとどめるべきです。それ以上のコメントは有害です。
私自身は実際に動作するコード(=いわゆるバイナリな形式)は枝葉で言えば葉っぱにある細胞の中のDNAレベルであると思うので、枝葉レベルまでを表現するためのドキュメント(=*.txtとか)とコードの間はグレーゾーンだと思います。
しかしながら、ソースコード(=*.cとか)は一定の人間が読み書きできる形式ですし、バージョン管理などがなされているのであればある意味それもドキュメントとしてとらえることができると思うので、上位のドキュメントに書くには細かすぎるような、いわば葉っぱからDNAレベルの間を埋めるようなことは書いてもいいとは思うのですが…
何から何まで上位ドキュメント参照にしてしまうとちょっと大変そうというか、ソースコードと上位ドキュメント間でコンテキストスイッチが多発するのはあんまりスマートじゃないなぁと思うわけでして。
ちなみに、将来にわたって明らかに問題・課題を残している場合はコメントで表現すべきレベルを逸脱しているので、それは上位ドキュメントやバグ管理システムに記述した上でコメント上はそこへのポインタを示しておくほうがいいと感じています。
# 業態などが違えば求められるドキュメント類が違うと思うので一概には言えませんが...# ドキュメントの内容をメンテナンスしないヤツは呪います(*.cにあるコメント含む)
> こういうことはコメントに書いてすませるべきではないですね。> プログラム(マ)だけの問題ではありませんから、きちんと周知しレビューすべきです。
> 問題点はドキュメントに整理し、コメントはそこへのポインタを示すにとどめるべきです。> それ以上のコメントは有害です。
> 状況がどうなるかは誰にもわかりません。コメントやドキュメントは変化していく状況のためのものでもあります。> 例え今は自分しか見る人がいなくても、プログラマの言い訳は(書くのなら)コメントに長々と書くのではなくきちん> とドキュメント化すべきです。
「すべき」がやたらと多いけど、あなたは実践しているの?(周りの人にも実践させられるの?)結構大変だと思うけど。
> 状況がどうなるかは誰にもわかりません。そりゃその通りだけど・・・元コメを否定するほどの理由とは思えないな。
どーでもいいですけど「hex化」って、「十六進文字列として解釈し、数値に変換する」処理のことなんでしょうか?もしそうだとすれば、なんだか違和感の残る言葉です。
総合的に云々 と書かれると政治家の答弁みたいで、結局何がどうベストなのか、どうするべきか分からないような…。
#きっとケースバイケースw
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
アレゲは一日にしてならず -- アレゲ見習い
表現の範囲は把握しておく (スコア:4, すばらしい洞察)
なので、それらを総合的に合わせて一番適切な表現になる様にするのがベスト。
なぜそのコードが選ばれたのか?の意図はコードには表れない。
コードは自分が何かは表わすけど、それだけ。選択の意図するものが
最善なのか次善なのか、それともやっつけなのかわざとなのかはコードの記述範疇外だから。
Re:表現の範囲は把握しておく (スコア:1, 興味深い)
思われる手法ではなにが問題だったかは長くなっても書いておくべきだと思います。
ドキュメントは仕様を理解したらそんなに見ないですし。
コメントが必要ないのが綺麗なコードなんていうのは80年代で終わってますから。
Re: (スコア:0)
> そうですよね。なぜこのロジックを選択するに至ったか、もっとシンプルと
> 思われる手法ではなにが問題だったかは長くなっても書いておくべきだと思います。
こういうことはコメントに書いてすませるべきではないですね。
プログラム(マ)だけの問題ではありませんから、きちんと周知しレビューすべきです。
> コメントが必要ないのが綺麗なコードなんていうのは80年代で終わってますから。
80年代で終わっているのは君のおつむのほうで。
Re: (スコア:0)
もし周知させることが必要であっても、それはコメントの必要性と排他ではありません。
また、周知の必要性も状況によって変わりますから、必ずしなければならないものでもありません。
意見に補足するというコメントなら秀逸だったんだろうけど、
「それは間違いで俺の意見が正しい」みたいな方向に走ったのは間違いでしたね。
Re: (スコア:0)
問題点はドキュメントに整理し、コメントはそこへのポインタを示すにとどめるべきです。それ以上のコメントは有害です。
> また、周知の必要性も状況によって変わりますから、必ずしなければならないものでもありません。
状況がどうなるかは誰にもわかりません。コメントやドキュメントは変化していく状況のためのものでもあります。
例え今は自分しか見る人がいなくても、プログラマの言い訳は(書くのなら)コメントに長々と書くのではなくきちんとドキュメント化すべきです。
Re:表現の範囲は把握しておく (スコア:1)
"表現の範囲は把握しておく"というサブジェクトに"すば洞"あげたいところです^^;
> 問題点はドキュメントに整理し、コメントはそこへのポインタを示すにとどめるべきです。それ以上のコメントは有害です。
私自身は実際に動作するコード(=いわゆるバイナリな形式)は枝葉で言えば
葉っぱにある細胞の中のDNAレベルであると思うので、枝葉レベルまでを表現する
ためのドキュメント(=*.txtとか)とコードの間はグレーゾーンだと思います。
しかしながら、ソースコード(=*.cとか)は一定の人間が読み書きできる
形式ですし、バージョン管理などがなされているのであればある意味それも
ドキュメントとしてとらえることができると思うので、上位のドキュメントに
書くには細かすぎるような、いわば葉っぱからDNAレベルの間を埋めるような
ことは書いてもいいとは思うのですが…
何から何まで上位ドキュメント参照にしてしまうとちょっと大変そうというか、
ソースコードと上位ドキュメント間でコンテキストスイッチが多発するのは
あんまりスマートじゃないなぁと思うわけでして。
ちなみに、将来にわたって明らかに問題・課題を残している場合はコメントで
表現すべきレベルを逸脱しているので、それは上位ドキュメントやバグ管理
システムに記述した上でコメント上はそこへのポインタを示しておくほうが
いいと感じています。
# 業態などが違えば求められるドキュメント類が違うと思うので一概には言えませんが...
# ドキュメントの内容をメンテナンスしないヤツは呪います(*.cにあるコメント含む)
Re: (スコア:0)
> こういうことはコメントに書いてすませるべきではないですね。
> プログラム(マ)だけの問題ではありませんから、きちんと周知しレビューすべきです。
> 問題点はドキュメントに整理し、コメントはそこへのポインタを示すにとどめるべきです。
> それ以上のコメントは有害です。
> 状況がどうなるかは誰にもわかりません。コメントやドキュメントは変化していく状況のためのものでもあります。
> 例え今は自分しか見る人がいなくても、プログラマの言い訳は(書くのなら)コメントに長々と書くのではなくきちん
> とドキュメント化すべきです。
「すべき」がやたらと多いけど、あなたは実践しているの?(周りの人にも実践させられるの?)
結構大変だと思うけど。
> 状況がどうなるかは誰にもわかりません。
そりゃその通りだけど・・・元コメを否定するほどの理由とは思えないな。
Re: (スコア:0)
していますし、実は周りの人に実践させられました。
> 結構大変だと思うけど。
あなたもバージョン管理システムでドキュメントを管理するでしょう?
何がどう大変だと思ったのですか?
> そりゃその通りだけど・・・元コメを否定するほどの理由とは思えないな。
いえ、本質は
・長すぎるコメント(特にプログラマの言い訳)はドキュメントにして別に管理すべき
ということです。
何か長いものを書くとして、どうしてそれがソースコード中でなければならないのですか?
Re:表現の範囲は把握しておく (スコア:1)
俺はコメントには「機能」を書きますね。どういう目的か。処理内容じゃなくって。
たとえば、0-9,a-z文字列("0123ab")をhex化(0x0123ab)するといった処理を書く場合、コードの塊の頭に
「// 16進文字列をHEXに変換する(端数が出たら残りは0x0埋め)」
とか。具体的に「// 文字列の長さを計測してループする」とか「// シフトして値をずらす」・・・とかって言うのはあんま書かないです。昔は書いてましたけど。
ところで、自分のソースの中に含まれるコメントの割合って行単位だと皆さんどのくらいあるんでしょうか?いわゆるコメント量のお話。昔自分の書いたコードを計測してきた結果、俺は「約30%」がコメント行でした。個人的にはこれくらいあれば(程度の差をあまり気にせず)分かってもらえると思います。
Re:表現の範囲は把握しておく (スコア:1)
「// 16進文字列をHEXに変換する(端数が出たら残りは0x0埋め)」
↓
「// ○○の項目に出力するために16進文字列をHEXに変換する(端数が出たら残りは0x0埋め)」
# 目的が抜けてました。
Re: (スコア:0)
どーでもいいですけど「hex化」って、「十六進文字列として解釈し、数値に変換する」処理のことなんでしょうか?
もしそうだとすれば、なんだか違和感の残る言葉です。
Re: (スコア:0)
Re: (スコア:0)
総合的に云々 と書かれると政治家の答弁みたいで、結局何がどうベストなのか、
どうするべきか分からないような…。
#きっとケースバイケースw
Re: (スコア:0)
ボクの場合、
プログラム言語に起こせる部分はプログラムに、起こせない部分は(自然言語
で)コメントとして書く。
みたいな感じです。