完了に関するマニフェスト

原文(投稿日：2010/03/19)へのリンク

Alixx Skevington氏は、ディスカッション・スレッドの発端となる完了に関するマニフェスト(Manifesto of Done)という記事を投稿した。氏は記事の中で、チームメンバ間での作業のクオリティに関する取り決めついて語っており、コードを通じてビジネス価値を提供するための取り決めを明確に示している。

• 有用なコードを記述するよう心がけます。コードは、他のメンバと連携しながら使用することを目的としているため、記述内容はすべて、このような行為に有意義な経験をもたらし、ワークロードを増加させるのではなく、軽減するものでなければなりません。
• チームで決められたスタイルに従ってコードを記述します。自分以外のメンバが、コードのメンテナンスおよび修正を行うことになるため、柔軟性のある設計をし、あらゆるテクノロジを利用してソリューションを確立します。このコードを記述する際には規約に従い、他のメンバがコードをメンテナンスできるようにします。
• メソッドを適度なサイズに保つことに同意します。大きなメソッドは、内容の追跡が困難であり、デバッグも難しくなるため、できる限り適度なサイズに保ち、このような複雑さを緩和します。
• すべてのコードにコメントを付けます。新規コードの作成か既存コードの変更かに関わらず、コードの内容を説明する短くて簡潔なコメントを付けます。これにより、後でコードを見るメンバは、コードの内容およびコードで実現しようとしていることを理解できます。
• コードのユニット・テストに同意します。これらのテストの再利用を可能にし、安定性を維持することに同意します。テストの内容と目的を明らかにすることにより、リファクタリングやバグの修正時に、他のメンバがこのテストを実行できるだけでなく、このコードで実現しようとしたことを理解できます。
• 既存コードのユニット・テストをメンテナンスすることに同意します。既存コードを変更または新たに機能を追加する場合は、すべてのテストをパスし、新しい機能にはいずれも新しいテストが存在するように心がけます。
• コード・カバレッジを80%以上とすることに同意します。コード・カバレッジをチェックし、記述するものすべてに価値がもたらされるよう心がけ、後で問題が発生してからコードの該当箇所に気付くことがないようにします。また、この数字を高めるよう努力します。
• コードが正しく結合されているかチェックすることに同意します。コードの記述が終了したら、同じ機能に取り組んでいる他のメンバと連携し、自分のコードが他のすべてのコードと問題なく動くか、また、必要な機能を提供しているかを確認します。

LinkedInにはこのリストに追加すべき項目を提案するコメントが多く寄せられており、これには次のようなものがある。

私は「チェックインの前にユニット・テストを再度実行する」を追加したいと思います。これを提案する理由は、一カ所に置かれている一見関係のないコードによって、別の場所のテストやコードに影響を及ぼす可能性があるためです。前回のプロジェクトでこのようなことが何度かありました。(David Kramer氏)

ユニット・テストに関する部分に対して: 私ならむしろ、「コードを書く前にユニット・テストを書く」に変更します。というのも、TDDを大いに信用しているからです。テストについてもう一つ言えるのは、「テストは製品コードであるがゆえ、それ相応の扱いをする」ということです。(Scott Ames氏)

コードのコメント行については、賛成できません。コメントが間違っていることは往々にしてあり、分かり切ったこと(/* set x to y */ x=y;など)が書かれていることもあります。また、常に余分な荷物を増やすだけで、それを実際のコードと一致するようにメンテナンスしなくてはなりません。記述が明確で、設計も分かりやすい優れたコードであれば、「コードの内容を説明する簡潔なコメント」は必要ありません。コードを見ればコードがどのように動くかは一目瞭然であり、SCMへのコミット時のコメントやバージョン間の差分によって、そのようになった"理由"が分かるはずです。また、見て分からないのであれば、分かるようになるまでリファクタリングすべきです。これとは別に、APIドキュメンテーションも厄介なものではありますが、一般に、コード・ファイルの読者ではなく、publicメソッドのユーザを対象としており、リリースされたアーティファクトの一部となっています。

完了に関する最も重要な定義が、暗に示されていますが、明確に考慮されるべきです。私はそれを最重要項目にしたいと思います。* 「機能の"完了"を定義する受け入れ基準はすべて、テストとそのテストをパスしたかによって示す。」