人生は短くて誰も読まないくらいのことを書いている。あなたがたわごとを書くなら、誰もそれを読まないでしょう。したがって、少し良いドキュメントが最適です。マネージャーはこれを理解していないことがよくあります。なぜなら、誤ったドキュメンテーションであっても、彼らがプログラマーに依存していないという誤ったセキュリティ感覚を与えるからです。誰かが本当に役に立たない文書を書いていると断言している場合は、「はい」と言って静かに仕事を探し始める。
ドキュメントの需要を緩和するために、適切なドキュメントを見積もりに組み込むのにかかる時間を正確に見積もることは、それほど効果的ではありません。真実は寒くて難しい：テストのようなドキュメントは、コードを開発するよりも何倍も長くかかることがあります。
良い文書を書くことは、まず第一に、良い書き方です。私はあなたが執筆、勉強、練習に関する本を見つけることをお勧めします。しかし、たとえあなたが卑劣な作家であっても、あなたが文書化しなければならない言葉の貧弱な命令を持っていても、黄金のルールは本当に必要なものです：「あなたが彼らにあなたのことをさせるように、他人に行います。誰があなたの書類を読んでいるのか、そこから抜け出す必要があるのか??、どのようにそれらを教えることができるのかを考えてください。そうするなら、あなたは平均的なドキュメンテーションライターであり、良いプログラマーになるでしょう。
プログラマー以外の人が実際に読むことができる文書を作成するのではなく、実際にコード自体を文書化することに関しては、私が今までに知っている最高のプログラマーは普遍的な感情を持っています：自明のコードを書いて、コード自体を書くことではっきりさせることはできません。これには、2つの理由があります。まず、コードレベルのドキュメントを参照する必要がある人は、ほとんどの場合、コードを読めるようになります。確かに、これは初心者よりも経験豊富なプログラマーにとっては簡単です。しかし、さらに重要なのは、文書がなければ、コードと文書は矛盾していないということです。最悪の場合、ソースコードは間違って混乱する可能性があります。完全に書かれていなければ、その文書はうそをつくことができ、それは何千倍も悪化します。
これは責任あるプログラマーにとってより簡単にはなりません。自明のコードをどのように書くのですか？それはどういう意味ですか？その意味は：
誰かがそれを読む必要があることを知っているコードを書く。
- ゴールデンルールを適用する。
- 別のソリューションを迅速に利用できる場合でも、簡単なソリューションを選択する。
- コードを難読化する小さな最適化を犠牲にする。
- 読者のことを考えて、彼女をもっと楽にする貴重な時間を費やしてください。そして
foo、bar、doItのような関数名を使用することはありません！