サウスポーなエンジニアの独り言

サウスポーなエンジニアが日々感じた、気づいた、学んだことを徒然と書いています。

ソフトウェア開発 旧館より

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

投稿日:2007年12月13日 更新日:


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

言いたいこと

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

その為の改善策は?

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

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

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

そもそもの問題提起

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

問題の発生原因

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

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

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

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

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

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

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

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

Photo credit: JD Hancock via Visualhunt / CC BY

-ソフトウェア開発, 旧館より

執筆者:


comment

メールアドレスが公開されることはありません。 * が付いている欄は必須項目です

関連記事

もっと会議の時間を有効に使いませんか?

今回は、ある会議に出ていて「もう少し効率良く時間を使えるなぁ」と思ったことを書きます。 出席者は地理的に離れている複数チームです。 チームごとのタスクは異なりますが、活動領域には重複する部分もあり協力 …

自分のTwitterアイコンの変遷

Twitterアカウントのアイコンは干支をモチーフにしたものですが、元ネタはヨメさんが年賀状用に描いていたものです。 #コミュニティなどで使う個人名刺にも使っていて、名刺の作成は前川企画印刷さんのブロ …

ワンランク上の問題解決の技術《実践編》 視点を変える「ファンクショナル・アプローチ」のすすめ[読書感想]

ワンランク上の問題解決の技術《実践編》 視点を変える「ファンクショナル・アプローチ」のすすめ 著者:横田 尚哉 問題解決がテーマの本は色々読みましたが、その中でも良書の部類に入ると思います。 ポイント …

教えてもらう、教える時に気をつけていること

仕事やバレーで教えてもらったり、教える(そこまでいかなくてもアドバイスする)ことが、ちょくちょくあります。 ↓は自分が教える = 伝え手の場合に気をつけていることです。 1:論理や順序の飛躍をしない …

“報・連・相”

“報・連・相”…新入社員研修等で耳にする言葉で、「それは非常に大事だ」ということも耳にたこができる位、聞いていると思います。 ところが実際、これが出来ていない人を多くみかけます …

ギルドワークスの現場コーチ。
「正しいものを正しくつくる現場を増やす」ことを目指している現場コーチ。認定スクラムマスター(CSM)。
様々な規模のSIerでのシステム開発を経て今に至る。
DevLOVE関西を主催。