yukiです。
今回は主にアジャイル開発におけるコード以外のドキュメントについてお話しようと思います。
「包括的なドキュメントよりも、動作するソフトウェア」という言葉がありますが、最近これを「ドキュメントはいらない」もしくは「極力書くべきではない」と誤解され、ドキュメントが軽視されがちだと感じます。
確かに、ドキュメントは面倒です。コードを書いている方が何万倍も楽しいですし。私も出来れば面倒なドキュメントは書きたくはありません。
「コード見ればわかるでしょ」とか「コードがドキュメントだ」と言い切るのは簡単ですし、事実そういった事もあるでしょう。というより、むしろその方が多いかもしれません。ですがコードをドキュメントとして扱うには、必要十分となるようなものでなくてはなりません。
そうではない(見てもわからんような)コードが多いのも事実ですし、それにドキュメントはまったく必要ないかといえばそうではない場合も多いですし、であればいっそ「(詳細な)ドキュメントを書かずとも済ませる」こと、「ドキュメントを書くことを楽しくする」ことを目指してみませんか？
問題点を把握する
なぜドキュメント軽視の状況になるのか、少し考えてみました。
- なぜドキュメントを書かないのか
- ドキュメントを書く時間がない
- なぜ時間がないのか
- 書く時間が工数に計算されていないから
- なぜ工数計算されないのか
- 成果として評価対象ではないから
- なぜ評価対象ではないのか
- 直接パフォーマンスに影響を及ぼすものでないから
- なぜパフォーマンスに影響を及ぼさないと認識されるのか
- 保守するコストを考慮しないから
- なぜ保守コストを考慮しないのか？
- 問題なく運用されて然るべきという危機意識(リスク)の欠如
- なぜ危機意識が欠如しているのか？
- もし○○したらという認識が不足している
まだ突き詰められるとは思いますし、まったく違った結果になったり、特殊な事情でこの限りではない場合もあると思いますが、このように認識の誤差から来るものが多いように思います。保守コストは無視できるものではないですし、運用後のリスクを考えると十分考慮して然るべきもののはずです。
評価体制を作る
ご存知のように、コスト削減はダイレクトに売上の向上に直結するものですから、もっと評価されてもよい箇所だと思うわけです。上記のような保守コストと運用リスクを天秤にかけた場合の意識の欠如や、属人的な開発を行った場合のリスクを軽視しているということが問題のようです。
リスクについてはあらゆる場面を想定し、実際に「そうなった」場合のコストを数字にして認識あわせを行い、ドキュメントを書く事そのものを評価し奨励する体制作りが重要です。
人的リソースを削減する
では、どうしたらコストは削減できるでしょうか。まず最もコストがかかることといえば人件費であり、つまり我々エンジニアの時間です。
なのでまず最初に「人が書く」ことそのものが削減できないかを検討してみましょう。ドキュメント作成においてもっともコストがかかる部分はどこか、なぜコストがかかるのかを徹底して突き詰めると、また違った形の問題が見えてくる事もあると思います。
この場合では、どうやったら最も人的リソースを消費せず自動化できるのかを考えるます。これはドキュメント生成の自動化ツールを作ってもいいでしょうし、そもそも生成せずともすむような形を考えるのもよいでしょう。
命名にもっと時間をかける
ドキュメントが古くなっていることもありますし、なんだかんだいっても、やはり最も信頼のおけるものは実際のコードです。
コードを読み込んで理解しようとする場合には、「3日たったら別人のコード」というようになかなか理解しづらいものですし、複雑になればなるほどそのコストは膨大なものになっていきます。このとき、よりこのコストを削減するにはやはり命名です。ざっと見ても理解できるような見通しのよい設計ももちろんですが、後々のクラスやメソッドの変更や追加が起こっても通用するような命名を心がけましょう。私自身が気をつけている点は、
- 重複しない
- 誤解しない
- 見ただけで内容がわかる
です。
よい命名は、ドキュメント生成ツールで作ったドキュメントであっても、とてもわかりやすいものになるはずです。
コミットログで説明
コミットログでは、誰が(Who)、何を(What)、いつ(When)、何処で(Where)、どのように(How)は付属情報でわかるのですが、なぜそうしたのか(Why)は人が書かない限りわかりませんので、何故こうしたのか、を必ず書くようにしましょう。
かいつまんでお話してきましたが、いかがでしょうか。
少しでもドキュメントを書く習慣が楽しく、楽になれば幸いです。