アカウント名:
パスワード:
きちんとドキュメントをまとめることができるプログラマのコードには、そもそもドキュメントは必要ない、ような気がする。
#経験則では、ないです。
これは間違い。
ドキュメントとコードが2つの異なる事を言っている場合は、最低限でもどちらかが間違っている(下手をすると両方間違っている)。
ドキュメントとコードが同じ事を言っている場合、両方をチェックする事でバグの存在を発見できる確率は飛躍的に高まる(人間は、同じ数学問題でも提示のされ方によって解きやすい場合と解きにくい場合がある)。
このように、ドキュメントは「内容確認」のために使うものなので、省いてよいものではないし、機械生成するべきものでもない。# 機械生成した場合は、プログラマ自身がそれを声に出して朗読するべきである。# 大抵、バグが見つかる。
きれいなコードなら内部設計書はいらないかもしれないけど、操作説明書の類はいるでしょ?
コードとドキュメントを読んでいって、どちらも読みやすい人と、どちらも読みにくい人のどちらかしか巡り合ったことのない私は不運でしょうか?
後者に限って、「ドキュメントなんて…」と言うわ、口頭説明も嫌がるわ、だったり。
> 読みやすいコードが書けないやつに、ドキュメントを書くなんてそもそも無理。
ものすごく同意できます。ドキュメントが書けないので不要論を展開する輩が多い。彼らはドキュメントに記述できる設計思想がないままコーディングしているのでしょうね。だからコーディング前には書けないし、コーディング終了後も明記できる設計がない。
#突貫(特攻)作業中に限り、脳内ドキュメントを許可する。(大本営特別指令)
>後になると自分でも何でこんなことをやったのか目的が理解できなくなることがある
その補足のために前のコードをコメントアウトして残したりしてたけど、上司から削除しろと言われたりしたっけ。
内容によるんじゃない?「変数がvolatileなのは・・・からアクセスされる為」とかコミットログに書いてあったら大変。
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
犯人はmoriwaka -- Anonymous Coward
憶測でコメントしますが (スコア:0)
きちんとドキュメントをまとめることができるプログラマのコードには、
そもそもドキュメントは必要ない、ような気がする。
#経験則では、ないです。
ドキュメントは、「プログラムが読めない人のためのもの」ではない (スコア:3, 興味深い)
これは間違い。
ドキュメントとコードが2つの異なる事を言っている場合は、最低限でもどちらかが間違っている(下手をすると両方間違っている)。
ドキュメントとコードが同じ事を言っている場合、両方をチェックする事でバグの存在を発見できる確率は飛躍的に高まる(人間は、同じ数学問題でも提示のされ方によって解きやすい場合と解きにくい場合がある)。
このように、ドキュメントは「内容確認」のために使うものなので、省いてよいものではないし、機械生成するべきものでもない。
# 機械生成した場合は、プログラマ自身がそれを声に出して朗読するべきである。
# 大抵、バグが見つかる。
fjの教祖様
Re:憶測でコメントしますが (スコア:2)
きれいなコードなら内部設計書はいらないかもしれないけど、操作説明書の類はいるでしょ?
Re:憶測でコメントしますが (スコア:1)
・外部仕様やデザインポリシーはメモ程度で良いのでドキュメント化しとくべき、後になると自分でも何でこんなことをやったのか目的が理解できなくなることがある。
・プログラムの内部仕様をドキュメント化するのは時間の無駄、そんなものを書く時間があるのならば綺麗な読みやすいコードを書くのに時間をかけた方が何倍もまし。
・読みやすいコードが書けないやつに、ドキュメントを書くなんてそもそも無理。
Re:憶測でコメントしますが (スコア:1)
コードとドキュメントを読んでいって、どちらも読みやすい人と、
どちらも読みにくい人のどちらかしか巡り合ったことのない私は不運でしょうか?
後者に限って、「ドキュメントなんて…」と言うわ、口頭説明も嫌がるわ、だったり。
Re: (スコア:0)
> 読みやすいコードが書けないやつに、ドキュメントを書くなんてそもそも無理。
ものすごく同意できます。
ドキュメントが書けないので不要論を展開する輩が多い。
彼らはドキュメントに記述できる設計思想がないままコーディングしているのでしょうね。
だからコーディング前には書けないし、コーディング終了後も明記できる設計がない。
#突貫(特攻)作業中に限り、脳内ドキュメントを許可する。(大本営特別指令)
Re: (スコア:0)
>後になると自分でも何でこんなことをやったのか目的が理解できなくなることがある
その補足のために前のコードをコメントアウトして残したりしてたけど、上司から削除しろと言われたりしたっけ。
Re:憶測でコメントしますが (スコア:1)
Re: (スコア:0)
内容によるんじゃない?
「変数がvolatileなのは・・・からアクセスされる為」
とかコミットログに書いてあったら大変。