ソースのコメントとドキュメントの関係

ソースを修正してもドキュメントを修正しないということはよくあることです。その結果使えないドキュメントがどんどん溜っていきます。

今日同期の一人がそんな問題を解決するための方法として、ある規約を考えました。その方法とはソースに履歴を書かない(ヘッダーを作成しない)というものです。ソースに履歴を書くのは当り前のことで、理由はそれがないと後からの保守作業などが困難になる為です。でも今回のプロジェクトはVSSを使用しソースのバージョン管理をしており、履歴がなくても修正個所は特定することができます。そして、どのような修正をしたかはドキュメントに記述するというきまりにします。

この方法のメリットは、今までのソースに履歴を記入しさらにドキュメントを修正するという二度手間がなくなること、修正履歴を記入するためにドキュメントを更新する機会が増えるというこどです。

デメリットはソースを見ただけでは修正履歴がわからずExcelやVSSが存在しない時は全く今までにどういう経緯があったかを想像できないということでしょうか。

ポイントは常にソースの最適化を意識すること(履歴を書かないため、ソースが汚くなることを防ぐことができる)と、ドキュメントの修正履歴の記入方法を工夫することです。

ドキュメントの修正履歴は始めに作った箇所はさわらず、別シートで変更箇所だけを追加記入していく方法がいいのではないかと考えています。

この方法に積極的に協力していきたいと思います。