ドキュメントは本当に無駄か？ − 設計とは整理すること

PM
  • ドキュメントを書くのは時間がかかるから省略する
  • ソースコードを見れば分かるので、ドキュメントは不要
  • 後からどうせ変わるので、ドキュメントは実装後に書く

というような、「ドキュメントは無駄」という旨の意見を見かけることがあります。

さすがに、仕事においては納品物ともなるため、一切ドキュメントを書かない、という人はいないと思いますが、詳細設計などの実装に近いドキュメントになればなるほど、そのような意見が多く出てきます。


ドキュメントを軽視している人の8割は、設計ができない人であり、そのような人が書くコードは、場当たり的で、拡張性が無かったり、共通化されない無駄なコードが多かったりします（あとの2割は、天才で、ドキュメントを書かずとも素晴らしいコードが書けるだけの能力がある人）。


何年も繰り返されている議論だろうけど、「ドキュメントは無駄」なのではなく「無駄なドキュメント」を書いているのが問題。

私自身は、ドキュメントを作成するのは、納品するためや保守で必要になるからではなく、自分の思考を整理するためと考えています。
頭で設計した内容を、具現化・詳細化していくために、設計書を書いていきます。


そのため、設計は一度で終わるのではなく、繰り返していきます。優秀なアーキテクトほど、自然とそのように行動していると思います。

頭の中で整理できたつもりでも、設計書という目に見えるかたちにすることで、

  • このようなパターンも考えられる
  • こうすればもっと美しい（拡張性や柔軟性のある）アーキテクチャになる


と、自分自身で問題点や改善点を発見することができ、改良を加えていくのです。
そのような設計書を元に実装されたコードは、設計書とかい離することもなく、コード自体も整理され、実装にかかる時間も短くなります。


価値のないドキュメントを作成する必要はないと思うが、今一度、ドキュメントの重要性を見直すのはどうだろうか。