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

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

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

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

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


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

言いたいこと

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

その為の改善策は?

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

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

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

そもそもの問題提起

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

問題の発生原因

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

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

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

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

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

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

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

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

Photo credit: JD Hancock via Visualhunt / CC BY

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

執筆者:


comment

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

関連記事

Redmineのチームでの使い方を紹介

Redmine Advent Calendar jp 2011の10日目になります。 私は(プラグインをガリガリ作ったりしてないので)「自分達のチームでの使い方」をいくつか紹介します。 コンテキスト …

えらくなっていきたいか?

ずいぶん前に書いたまま放置していたのを(ちょっと書き足して)アップします。 組織において「えらくなっていきたいか?」という話です。 えらくなりたいか?の問いに対して 一時期「昇格/昇級したいか?」とい …

How to Change the World 〜チェンジ・マネジメント3.0〜

 「How to Change the World 〜チェンジ・マネジメント3.0〜」を読み終えました。  以下、自分用のメモ書きですが、感想などを。 クイック・ウィンは、フィードバックを増幅し、その …

自分が議事録を書く際に気をつけていること

「議事録」は社内外の会議、打合せ、レビュー等のアウトプットです。 良い議事録を書く留意点、テクニックは色々あり、例えば… 1営業日以内に書く 記憶は曖昧で、かつ、あっという間に別のタスクが入ってくるの …

チームへのRedmineの効果

Redmine Advent Calendar jp 2011の25日目になります。 #余談。本場のAdvent Calendarは「24日まで」を窓を開けていくことでクリスマスを祝うそうです。一方、 …

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