アカウント名:
パスワード:
コードを書きながらできるだけ詳細にコメントを付ける。 書きあがったらバグ出ししつつコメントも修正する。 できあがったらコメントを読みつつドキュメントを書く。
こうするとソース見ただけで概要がつかめるし、ドキュメントとコードの齟齬もないということでした。 言われたときにはピンとこなかったんですが、先輩の卒論に添付のソースとドキュメントを読んだ時には納得しました。確かに分かりやすいしコードとドキュメントに矛盾がありません。うまい手だと思いました。 でも、現場の進行を考えると時間食い過ぎで採用されにくい方法だと思います。せっかくの知恵なのに。
後輩にソースへのコメント記載の意義を理解してもらうために、こんな説明をしています。
・コードを書く前に処理内容をコメントで書く事・(設計書がある場合)なるべく設計書の記載を使用する事・コメントを書いたら、コメント通りにコーディングする事
言葉で説明できないコードを書かなくなるので、意味不明なコードが減ります。
・コーディングが終わったら最初に書いてたコメントを消す事
っていうステップが抜けてますね。
コメントは処理内容を書く場所ではなく、「なぜその処理を書くに至ったか」などコードだけでは表せない情報を補足として書く場所です。
より多くのコメントがこの議論にあるかもしれませんが、JavaScriptが有効ではない環境を使用している場合、クラシックなコメントシステム(D1)に設定を変更する必要があります。
にわかな奴ほど語りたがる -- あるハッカー
大学で教わりました。 (スコア:5, 興味深い)
こうするとソース見ただけで概要がつかめるし、ドキュメントとコードの齟齬もないということでした。
言われたときにはピンとこなかったんですが、先輩の卒論に添付のソースとドキュメントを読んだ時には納得しました。確かに分かりやすいしコードとドキュメントに矛盾がありません。うまい手だと思いました。
でも、現場の進行を考えると時間食い過ぎで採用されにくい方法だと思います。せっかくの知恵なのに。
Re:大学で教わりました。 (スコア:1)
後輩にソースへのコメント記載の意義を理解してもらうために、こんな説明をしています。
・コードを書く前に処理内容をコメントで書く事
・(設計書がある場合)なるべく設計書の記載を使用する事
・コメントを書いたら、コメント通りにコーディングする事
言葉で説明できないコードを書かなくなるので、意味不明なコードが減ります。
Re: (スコア:0)
・コーディングが終わったら最初に書いてたコメントを消す事
っていうステップが抜けてますね。
コメントは処理内容を書く場所ではなく、「なぜその処理を書くに至ったか」など
コードだけでは表せない情報を補足として書く場所です。