コードとしてのドキュメント

2005年3月22日

アジャイル手法の共通要素の1つは、ソフトウェア開発においてプログラミングを中核的な役割に高めることです。これは、ソフトウェアエンジニアリングコミュニティが通常行っているよりもはるかに大きな役割です。これの一部は、コードをソフトウェアシステムの主要なドキュメント、あるいは主要なドキュメントと分類することです。

すぐに、よくある誤解を解く必要があると感じます。このような原則は、コードが唯一のドキュメントであると言っているわけではありません。エクストリームプログラミングについてこう言われるのを何度も耳にしてきましたが、エクストリームプログラミング運動のリーダーがこう言っているのを聞いたことはありません。通常、コードを補足するさらなるドキュメントが必要です。

コードを主要なドキュメントソースとする根拠は、それがその役割を果たすのに十分な詳細さと正確さを備えた唯一のものであるということです。これは、ジャック・リーブスの有名なエッセイ「What is Software Design?」（http://www.developerdotstar.com/mag/articles/reeves_design_main.html）で雄弁に述べられています。

この原則には重要な帰結があります。つまり、プログラマーは、このコードが明確で読みやすいことを確認するために努力することが重要です。コードがドキュメントであると言うことは、特定のコードベースが良いドキュメントであると言っているわけではありません。あらゆるドキュメントと同様に、コードは明確であることも、わけのわからないものになることもあります。コードは、他のいかなる形式のドキュメントよりも本質的に明確であるわけではありません。（そして、他の形式のドキュメントもひどく不明瞭になる可能性があります。私は、人気の高いUML図のわけのわからないものもたくさん見てきました。）

確かに、ほとんどのコードベースはそれほど良いドキュメントではないようです。しかし、コードをドキュメントとして宣言することが他の形式を除外するという誤謬であるのと同様に、コードがしばしば貧弱なドキュメントであるからといって、それが必然的に貧弱であると言うのも誤謬です。明確なコードを書くことは可能です。実際、私はほとんどのコードベースをはるかに明確にすることができると確信しています。

コードがしばしば読みづらい理由の一部は、人々がそれをドキュメントとして真剣に受け止めていないからだと思います。コードを明確にしようという意志がなければ、それが自力で明確になる可能性はほとんどありません。したがって、明確なコードへの第一歩は、コードがドキュメントであることを受け入れ、それを明確にするために努力することです。これは、ほとんどのプログラマーがプログラミングを始めたときに教えられたことに起因すると考えます。私の教師たちは、コードを明確にすることにあまり重点を置いていませんでした。彼らはそれを重視しておらず、それをどのように行うかについても話していませんでした。私たちは業界全体として、コードの明確さを重視することにるべく、もっと重点を置く必要があります。

次のステップは、どのように行うかを学ぶことです。ここでは、ベストセラーの技術書の著者のアドバイスをご紹介します。レビューほど良いものはありません。私は、多くの人に読んでフィードバックをもらわずに本を出版しようとは思いません。同様に、明確なコードにとって、他の人から何が理解しやすいか、何がわかりにくいのかについてのフィードバックを得ること以上に重要なものはありません。ですから、他の人々にあなたのコードを読んでもらう機会を最大限に活用してください。彼らが理解しやすいと思うものと、混乱させるものを調べてください。（はい、ペアプログラミングはこれを行うための素晴らしい方法です。）

より具体的なアドバイスとしては、プログラミングスタイルに関する優れた書籍を読むことをお勧めします。Code Completeが最初の候補です。もちろんリファクタリングも提案します。結局のところ、リファクタリングの多くはコードをより明確にすることです。リファクタリングの後には、Refactoring to Patternsも当然候補となります。

さまざまな点で意見が食い違うことは常にあります。コードベースは主にチームが所有していることを忘れないでください（個々のコードの所有権を一部に適用する場合でも）。プロのプログラマーは、自分のスタイルを曲げてチームのニーズを反映させる準備ができています。そのため、三項演算子が気に入っていても、チームが理解しにくい場合は使用しないでください。個人的なプロジェクトでは独自のスタイルでプログラミングできますが、チームで行うことはすべて、そのチームのニーズに従う必要があります。

2015年3月25日再投稿