アカウント名:
パスワード:
客が「なぜ」そうしてほしいかを書けばそれが(要求)仕様書。エンジニアが「なぜ」そう作るのかを書けばそれが設計書。
優れたドキュメントは、第三者が見たときに「なぜこうなってる?」という疑問に答えてくれる。コードだけで上記が全て表現できるのであればそれでもいいけど、現実には無理だからね。
「なぜそうするか」がない書類多いですね。(コメントを含む)
持論としては、[1] 「これこれこういう理由でこういう処理をする」とコメントをつけた ソースコードは資料になりうる。論理的にも正確だし。現物だし。[2] ただしあんまり詳細すぎて読み込まないと理解しづらいし、ソースは視点が ミクロなので、マクロな視点の「読み物」を書いて残す。
がベスト解ではないかと個人的には思います。
C言語で、「同じものは二度書かない」ってルールがあるじゃないですか。だから関数名やら引数やらをコメントで二度書いて、さらにドキュメントに三度書くのはまったくの無駄だと思う。
そしてソース中のコメントにしても、読み物にしても、しかたなく投げやりに書いてはいけないのです。追い込まれてつい flag, flg2 なんて変数を宣言してはいけないのです。処理を切り替えるなら #if WHEN_TESTING_SOMETHING を使うべきで片方をコメントアウトでは手順がロストしてしまう。
そうして残った各種のファイル、コードは Makefile にまとめるとソースと生成物の関係がはっきり残りますし、書きちらした読み物は HTML でFAQ的にまとめるといい感じにまとまることが多いです。時系列は常に重要です。
これらを実現するためには、ものぐさなeditではだめです。文字編集能力は高いほどいいし、文学的ボキャブラリーも重要です。
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
計算機科学者とは、壊れていないものを修理する人々のことである
シンプルに考えよう (スコア:0)
客が「なぜ」そうしてほしいかを書けばそれが(要求)仕様書。
エンジニアが「なぜ」そう作るのかを書けばそれが設計書。
優れたドキュメントは、第三者が見たときに「なぜこうなってる?」という疑問に答えてくれる。
コードだけで上記が全て表現できるのであればそれでもいいけど、現実には無理だからね。
Re:シンプルに考えよう (スコア:1)
「なぜそうするか」がない書類多いですね。(コメントを含む)
持論としては、
[1] 「これこれこういう理由でこういう処理をする」とコメントをつけた
ソースコードは資料になりうる。論理的にも正確だし。現物だし。
[2] ただしあんまり詳細すぎて読み込まないと理解しづらいし、ソースは視点が
ミクロなので、マクロな視点の「読み物」を書いて残す。
がベスト解ではないかと個人的には思います。
C言語で、「同じものは二度書かない」ってルールがあるじゃないですか。
だから関数名やら引数やらをコメントで二度書いて、さらにドキュメントに三度書く
のはまったくの無駄だと思う。
そしてソース中のコメントにしても、読み物にしても、しかたなく投げやりに書いては
いけないのです。追い込まれてつい flag, flg2 なんて変数を宣言してはいけないのです。
処理を切り替えるなら #if WHEN_TESTING_SOMETHING を使うべきで片方をコメントアウトでは
手順がロストしてしまう。
そうして残った各種のファイル、コードは Makefile にまとめるとソースと生成物の
関係がはっきり残りますし、書きちらした読み物は HTML でFAQ的にまとめると
いい感じにまとまることが多いです。時系列は常に重要です。
これらを実現するためには、ものぐさなeditではだめです。
文字編集能力は高いほどいいし、文学的ボキャブラリーも重要です。