ドキュメント修正の大事さ

プロジェクトメンバー、リーダーとしての振り返りで毎回思っては実現できていなかったことを備忘録として書いておきます。

言いたいこと

仕様書等のドキュメントの作成/修正が後付けになったりして、ソースコードとそれらドキュメントとの乖離を出さないようにしましょう。

新規、保守開発問わないシステム開発で、(仕様変更や実装結果を反映する)「ドキュメント修正」をWBSのタスクとして明確にします(ちなみにこれを「バッファやん」なんて甘い考えを持っているようではダメです)。

変更管理、不具合管理のフローにおいても「プログラムが正しく修正されていることを確認する」が終了条件では無く(たいがいはこれで終わっていると思います)、「該当の仕様書、テストケース(つまりドキュメント)が修正されていること」を終了条件とすることで、プロセス面でアプローチをします。

もう1つは自分がドキュメントがグダグダなシステムを保守/修正して、大変な痛い目をあって実感すること(できれば裏返しの成功体験も掴んで欲しいですが)です(「喉元過ぎれば熱さを忘れる」はありますが…)。

ソースコードとドキュメントの乖離で、何が困るかと言うと、保守や機能追加/修正時に役立たず、工数の増加を招きます。さらに悪いことにそのドキュメントを信じて進んだ場合、システム障害を引き起こしお客様に迷惑がかかります。

よく聞くのは「時間が無い」「面倒くさい」というものです。

[1]「時間が無い」
余裕のあるプロジェクトなんてなく、バッファなんぞは予期せぬ出来事でアッという間に食いつぶされていきます(バッファがあるだけマシです)。「そんな紙よりも実際に動くものを作る方が良い」という感覚も開発者にはあります。

[2]「面倒くさい」
新規開発中やそこそこの機能追加であれば、仕様書の作成中、実装中に「やっぱり…」と仕様変更/追加になることはままあることです。
その都度、仕様書に反映させるのは非効率で、ある程度Fixしてから反映すれば良いというわけです。

「ドキュメントは大切ですよ～」と話になると「意味の無いドキュメントなんかより、ソースコードが全てだ。ソースコードがドキュメントだ。」とXP(エクストリーム・プログラミング)かぶれ？な発言をする人がいます。

確かにXPにはそういう思想もあるとは思いますが、あくまで「不必要なドキュメントは作らない」というもので「ドキュメント全てを不要」なわけではありません。

それに「ソースコードがドキュメントだ」なんて言うからには、そのソースコードは適切なコメントから始まり、変数、メソッドの命名規約、分かりやすいアルゴリズム(なぜこういう処理なのかが手に取るように分かる)…つまりCodeCompleteを実践しているような…であることが前提です。

で、上記のような発言をする人に限って、大したソースコードじゃない…むしろ非常に読みづらく理解に苦しむソースコードな気がします。
良いソースコードを書ける人はドキュメントの重要性も理解している方が多い気がします(少なくとも私が出会った人の中にはこれを理解していない人はほとんどいません)。

※注意：この記事は旧サウスポーなエンジニアの独り言から移行し一部修正したエントリです。