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

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

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

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

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


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

言いたいこと

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

その為の改善策は?

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

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

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

そもそもの問題提起

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

問題の発生原因

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

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

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

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

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

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

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

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

Photo credit: JD Hancock via Visualhunt / CC BY

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

執筆者:


comment

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

関連記事

嬉しい言葉「また一緒に仕事をしたいですね」

「またこのチームの皆さんと一緒にプロジェクトをしたいですね!」 システムのカットオーバーを無事に迎えたプロジェクトの打ち上げで、クライアントからこんな言葉をもらえるとすごく嬉しいものです。 こういう言 …

未来の自分を信頼し過ぎない

プログラミングにおいて他者のことを考えて「分かりやすいコードを書きましょう」「適切なコメントをつけましょう」というのは基本的なことです。 この「他者」には、そう遠くない「未来の自分」も含まれています。 …

朝早く仕事に取りかかるメリット

以前エントリ「自分のテンションを維持する方法」で「朝早く出社する」ことを書きました。 これを少し詳しく自分なりに考えてみました。 まずはやはり朝早くの時間帯は静かで本当に集中できます。電話ももちろん話 …

「レビュー」タスクの見積もり

1~3年目のような経験の浅い方が見積もる「レビュー」タスクの工数について思うことがあります。 レビューはある成果物…提案書や設計書、ソースコードなど…を個人/複数のメンバー…たいていはプロジェクトリー …

ドキュメントを書くために気をつけていること

#ソース元は「誰にでも伝わるSEのための文章術-第6回 読みやすい文章の極意は「修飾語」にあり」です。 「あぁ、そうやなぁ」と思うようなことが、分かりやすい例とともに記述されています。 今まで書いたド …

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