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

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

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

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

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


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

言いたいこと

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

その為の改善策は?

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

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

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

そもそもの問題提起

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

問題の発生原因

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

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

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

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

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

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

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

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

Photo credit: JD Hancock via Visualhunt / CC BY

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

執筆者:


comment

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

関連記事

継続的な受付窓口って必要

ふとあるミーティングで熱く議論した後に思ったことです。 色々な組織レベルで、「会社を活性化するには?」とか「売上を伸ばすにはどうしたら良いか?」という類のアイデア出しやブレーンストーミングを目的とする …

会議でメンバーが意見を言いやすくなる方法

会議が「20人以上」かつ、担当者レベルからマネージャ、部長クラスが「一堂に会する」ような場合、活発な議論、質疑応答が飛び交うことは稀かと思います。 部長から一方的に報告や連絡事項が行われ、他のアジェン …

テスト工程

…とは言っても、学校の「期末試験」でなく、システム開発での「テスト工程」のことです。 今のプロジェクトが、そろそろお客様先での結合テストに入る…と、スケジュール上なっています。 しかし現実は単体テスト …

あるフリカエリにて。

あるフリカエリをして、しばらく時間が経ってから思ったことです。 性格やクセに起因する、固有の行動特性は、『簡単』には変わらない…と思いました。 変わるには、それなりの意志の強さが必要だったり、周囲の状 …

プロジェクトにおける「割れ窓理論」

環境犯罪学上の理論に「割れ窓理論」というのがあります。 「建物の窓が壊れているのを放置すると、誰も注意を払っていないという象徴になり、やがて他の窓もまもなく全て壊される」(Wikipediaより) 有 …

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