コードは最上級のドキュメントになり得るか

はじめに

という記事を投稿したところ、多くの方からコメントいただきました。
上記事は私のマネジメント失敗談を書いたものですが、私と同じように設計ドキュメントを正とする考えもあれば、コメントやドキュメントよりもコード！という考えもあるとわかりました。

そこで、果たしてコードが最上級のドキュメントになりえるのかを考察したいと思います。

ディスクレーマー

本記事はコメントしてくださった方を批判するものではありません。
誤解のなきようお願いいたします。

最上級とは

ここで最上級とはドキュメントに取って代わることができるつまりコードだけでプロダクト活動に包含される概念を示すことができる、という意味とします。

つまり、コードさえあればドキュメント無しでプロダクト活動（プロジェクト）は成立するということです。

ドキュメントとは

ここでドキュメントとはDDDの文脈におけるドキュメントを指すことにします。

• ドキュメントはコードや会話での表現を補うものである
• コードでうまくやれていることをドキュメントでやるべきではない
• ドキュメントは活動に組み込まれていなければならず、最新の状態になる
• 等など

またドキュメントの一部になり得るコメントも、リーダブルコードやプリンシパルオブプログラミングにあるように、意味のあるコメントを指すことにします。

• 自分の考えを記録する
• コードの欠陥を記録する
• 他者への注意や警告
• なぜこのようなコードになっているか（Why）を記録する
• 等など

仮定：コードだけがある状態

コードだけが存在する場合を考えてみます。

コードだけが存在し且つコードがプロダクト活動の全てを表現可能なのであれば、確かにドキュメントやコメントは不要です。
例えば、小規模プロダクトや個人開発等でしょうか。

では、それ以外のあらゆる場面においてコードが全てを表現できるのでしょうか。

コードが全てを表現できる とは

繰り返しになりますが、ドキュメントやコメントの内容がコードに表出するということです。

例えば、会話の中で発せられた微妙なニュアンスであったり、自分の考え、コードの欠陥、注意、Whyです。
そのようなコードを書くとすれば以下のようになります。
言語はGoです（言語は特に問題ではありません）。

package main

func doSomethingWithQuickSortAlgorithmBecauseXXX() {
    // Do something with the quick sort algorithm
    // because ...
}

上記のコードはXXXという理由によってクイックソートを用いて何らかの処理を行う関数を示しています。
つまりコードはWhyを示しているのです。

このコードは最上級のドキュメントになり得るか

私はこのような関数（関数名に背景を含む）をあまり見たことがありません。書くとしても func doSomething でしょう。
そしてなぜそうしたかはコメントに残すでしょう。
複雑な背景がある場合やステークホルダーが多い場合はドキュメントという表現手法を用いるのが適切で、なぜ適切なのかというとあらゆるステークホルダーが理解可能な自然言語で表現でき、文字以外での表現も可能だからです。

package main

// doSomething returns ... 
// This function uses the quick sort algorithm
// because ...
func doSomething() {
    // ...
}

上記の例は突拍子もない例ですが、実際は関数名を簡潔に示すことが多いと思います。

またこのコードは活動の一部しか表現できていません。活動とは絶え間なく続くプロセスであり、プログラミング言語という一種のフィルタを通した時点で情報はいくらか欠落してしまいます（このコードからプロダクト活動が透けて見えますか？）。

つまりコードは最上級のドキュメントになり得るごく稀なケースを除いて、通常はコードだけで表現せず、ドキュメントやコメントといった適切な情報伝達手段を用いるというのが個人的見解です。

まとめ

当然と言えば当然ですが、状況（プロダクト規模等）によってコードがドキュメント並の表現力を持つ場合もありますが、それ以外の表現手段（ここで言うドキュメントやコメント）を全く用いなくてよいかというとそういうわけではありません。

誰に対して何を伝えるかを念頭に、どのような手段であればそれが上手く伝わるかを考えることが大切だと思います。

最後に

皆さんのご意見お待ちしています。