プログラマーがドキュメントを書かない理由

2021/05/11 09:18

Kislay Verma
プラットフォームアーキテクチャのエバンジェリスト
この記事は、著者の許可を得て配信しています。
Why programmers don’t write documentation

最近ではずっとコードのドキュメンテーションに関連した記事を書いていたので、当然、私のMediumのおすすめ記事には「開発者がドキュメントを書かない本当の理由」という記事が表示されるようになりました。この記事では、ドキュメントを書くための優れたツールがないことが、ソフトウェアエンジニアが自分の作業や判断をドキュメンテーションする意欲を失わせる最大の原因について書いています。

私は普段、特定の記事を批判したりはしませんが、この記事には怒りを覚えました。このライターは図解ツールについていくつかメリットに関して述べてはいますが、全体的に誤解を招くような内容になっており、この重要な問題をより分かりにくくさせています。2つの図解ツールを比較して、どちらも不十分なツールであるということが開発者がドキュメントを書かない主な理由だと主張するつもりなら、この記事はクリックベイトのために書かれているか、悪意を持って書かれているかのどちらかです。

私は、ソフトウェアエンジニアがドキュメントを書かない理由は主に2つあると考えています。ツールはその役割を果たしていますが、メインの理由ではないと考えています。

書くということの難しさ

ソフトウェアエンジニアは、他の人のようにドキュメントを書きません。なぜなら、明確に書くことが本当に本当に難しいからです。

書くというのは、とても大変な作業です。考えを明確に整理し、批判的に吟味し、明確に表現することが必要です。表現という面においては、ある程度簡略化できますが(必要とされる文章の質にもよりますが)、この3つのステップは確実に行うとかなり重荷になるものです。

プログラミングの世界では、「場合によりけり」というのが最良の答えであることが多く、すべてがトレードオフの上に成り立っているので、ドキュメント書くことはそれだけ難しくなります。文脈を設定し、自分がした行為の理由を説明し、コードにつながるローレベル思考を後押しする必要があります。このように書くということは、うまくいった場合にのみ役立つものですが、うまくいくこと自体が少ないので、まったく書かれないことも多いのです。質の悪いコードはまだ受け入れられても、ドキュメントではそうはいきません。

だからこそ、多くの人がコードのコメントの価値や、セルフドキュメント化のメリット(それがどんな意味であれ)について議論しているのです。Kevlin Henney氏は、複雑なコードにコメントを求めても無駄だと言っています。なぜなら、コードで明確に表現できなかった人たちに、今度は英語で明確に表現することを期待しているからです。

A common fallacy is to assume authors of incomprehensible code will somehow be able to express themselves lucidly and clearly in comments.

— Kevlin Henney (@KevlinHenney) September 20, 2013

ドキュメントを書かなくても出荷は妨げられない

開発者がドキュメントを書かなくても、仕事は終了です。ドキュメントを書かなくても、出荷が妨げられることはありません(少なくとも、すぐには)。技術的決定をドキュメンテーションしないことによる痛手は累積していくのです。技術的負債と同じく、すぐにダメージを受けるわけではありません。

上でも述べたように、ライティングは主に思考と分析の問題です。ほとんどの場所で、コーディングはちょっとした経験があればできるものです。整理されていないクラスやメソッドのコードを処理するのは問題なくても、言葉や文章を書くような作業はそうはいきません。書くということが明確であれば、その意味があります。コードはその機能を果たしている限り、(ある程度)は受け入れられます。そして、ほとんどの組織は製品を出荷することだけに集中しているので、出荷を妨げないものは無視されてしまうのです。

多くのチームが、ユニットテストに関して同様の問題に直面しています。コードをテストするためには、コードを理解する必要がありますが(それはコードを書くよりも労力がかかります)、テストがなくても出荷を妨げることはありません。そのため、コードにユニットテストは含まれていません。

また、優れたドキュメントであっても陳腐化してしまうため、エンジニアはシステムを構築する際に何度も「考える」「分析する」「表現する」を繰り返さなければなりません。そのため、ドキュメント作成の手間を省くことは容易です。良かれと思って作成したドキュメントも、書いては消し、書いては消しの繰り返しになってしまうのです。

ツールについて

現在、ソフトウェアのドキュメント作成に使用されている一般的なツールは、非常に不十分なものであることは間違いありません。私たちは、ひとつひとつのドキュメントから考えることはないのです。一度に複数のコンセプトをまとめて、アイデアやゴールを考えます。結果として得られるドキュメントは、その思考プロセスの一つの表れに過ぎません。問題解決のためには、時間を超えてアイデアを集約するためのツールが必要です。Google Docs、Confluence、Markdownなどは、この種のドキュメンテーションには不向きなツールです。

しかし、NotionRoamのような新世代のツールは、ネットワークを利用するというこの問題に取り組んでいます。願わくば、これらのツールが期待していた通りに機能し、執筆に必要な思考を助けてくれることを願っています。

しかし、二つ目の脳がないからといって、一つ目の脳を使わないことの言い訳にはなりません。道具も大事ですが、自分でやろうという気持ちが本当のハードルなのです。

ドキュメンテーションをどうするか

ソフトウェアを作っていて、一つのことを学びました。ユーザーに本当に何かをしてもらいたいのなら、それをすることが製品を使う手順において重要な手順にならなければならないということです。それと同じように、書かれたコードにドキュメントを付け加えることは、決してうまくいきません。もっと言えば、役に立たないのです。書くということは、クリティカルシンキングのことです。自分の思考プロセスや意図を、自分自身や周りにいる人たち(自分のチームなど)に説明するためのものです。思考プロセスこそが、ドキュメントや書くことの価値を高めるものであり、すでに実装されたコードのスタティックな記録ではありません。

モブ(ペア)プログラミングやXPを支持している人たちが、ドキュメントを軽視しているところもあるのは事実です。しかし、そのような技術を採用しなくても、技術的なドキュメントを書いたり吟味したりすることは、チームが構築しようとしているものについての総合的な理解を深める唯一の方法です。共有された世界を構築することで、このプロセスがチームとコードベースの長期的な健全性にとって重要なものになるのです。

ドキュメントを書くというプロセスを持続可能なものにするには、ソフトウェア開発の妨げになるようなものにするしかないと思っています。そこまで負担にならないまでも、必須のものにするのです。ドキュメンテーションは、やるべきことの一つではなく、プロセスの一部になるべきです。私の経験から、このために有効だったものがいくつかあるので、ご紹介したいと思います。

  • コードを書く前に書く - 些細な変更でない限り、すべてのエンジニアは自分が何をしようとしているのかメモを書き、チームの他のメンバーに実行してもらいます。議論の最後には、実際のコーディングは一般的なものになるはずです。
  • シンプルに書く - 少なくとも、自然にできるようになるまでは、文章を複雑にしないでください。図解や段落などは後回しにするのです。自分が何を考え、何をしているのか、そしてその理由を非常にシンプルに書きましょう。たとえそのドキュメントが、チームの他のメンバーにとって、基本的な指針としての機能しか持ち合わせてなくても、それは非常に価値のあるものです。
  • 決定事項とその代替案をドキュメントにする - 実際の実装(時間の経過とともに変更される可能性がある)を詳細にドキュメンテーションするのではなく、選択事項とその理由をドキュメンテーションすることに集中してください。これはコードでは説明できないことであり、それを書き留めることでそのドキュメントが価値のあるものになります。書く人がかける時間によって変わりますが、詳細をドキュメンテーションしてもよいでしょう。
  • 検索可能にする - いくらドキュメントを作成しても、人々がそれを見つけられなければ意味がありません。すぐにテキスト検索ができるツールを使いましょう。私がドキュメント用のGoogle Docsを好まない理由はここです。Google Docsは文章を書くのには適していますが、共同作業や検索には向いていません。
  • 変更を追跡する - 一部の組織では、バージョン管理を使用して、システムの設計に対する時間の経過に伴う変更を追跡しています。それは素晴らしいことです。しかし、まだそこまで至っていないのであれば、機能ごとに1つのドキュメントを用意し、そこに日付入りの更新情報を載せ続けることで、変化を手間をかけずに1箇所で追跡できることができるようになります。

ドキュメント(新入社員にはあまり手をかけない方がいいなど)を持つことや見直すことのメリットがチームに伝わり、書くことが習慣化されることで、この習慣が条件反射的になり、継続されていくことを期待しています。それまでは、エクササイズやダイエットのように、苦しいけれど必要なことだと思ってください。

appstore
googleplay
会員登録

会員登録して、もっと便利に利用しよう

  • 1.

    記事をストックできる
    気になる記事をピックして、いつでも読み返すことができます。
  • 2.

    新着ニュースをカスタマイズできます
    好きなニュースフィードをフォローすると、新着ニュースが受け取れます。