2018-02-10

身につけるべきプログラマの習慣 その2

継続的にメンテナンスできないドキュメントは書かない

もしあなたに作成ドキュメントの選択権があるならば、まず第一に新規作成より修正のことを念頭に無駄を排除すべきです。

大きなプロジェクトほど無駄なドキュメントを作成する傾向が感じられます。最初に作成したはいいが、結局それが何の為に存在しているのか誰にも理由がわからず、そして役に立たない。役に立たない一番の原因は、メンテナンスが行き届いていないため、内容をどこまで信用していいのかさえ判らなくなっているからです。

少なくとも、システムの内容に変更が生じたときは、修正すべきところを全て洗い出すことができなくてはなりません。そして、修正すべきであることを直接ドキュメントに印を付けることが重要です。修正後の内容を書き込むのは後でもいいので、とにかくその内容が違ってしまったことがはっきりと判るようにだけはしておきましょう。その際、修正IDを併記しておくと良いでしょう。
そのようにしておけば、もしそのままの状態で放置されてしまったとしても、印の付いていないところはまだ信用できることが判るので、ドキュメント全体が死んでしまうことはなくなります。

同じ内容は1箇所だけに書くようにしろ、という教えもありますが、それは無理があります。もちろん、極力重複は排除すべきですが、概要と詳細に分かれていたり、図面と文章に分けて表現する等、どうしても複数箇所に同一内容が記載されてしまいます。

これらのことを踏まえて、確実にメンテナンスできるドキュメントを作成するように心がけましょう。

とは言え、ドキュメントは必ず書かなければなりません。どうせメンテナンスできないのだから、という理由でドキュメントの作成を放棄するのは大間違いです。
それは、ひょっとするとコンパイルしてバイナリが生成できたら、ソースファイルを廃棄するのと同じかも知れませんよ。


0 件のコメント:

コメントを投稿