何が試されて何がうまくいかなかったかを他の開発者に知らせる方法は？
たとえば、開発者がコードベースに特定の機能を実装する必要があるとします。その開発者は、デザインA（特定のデザインパターンなど）を使用して機能を実装しようとします。開発者は、実装の途中で、デザインAを使用することは最初は魅力的なソリューションのように見えますが、実際には解決するよりも多くの問題を引き起こすことに気付きました。したがって、彼は先に進み、機能を実装するためにデザインBを使用することを決定します。
この開発者は、将来の開発者（自分自身を含む）に、この機能の実装でデザインAを使用することから離れるべきだとどのように伝えますか？開発者は、これを実行して、他の開発者が、以前にすでに試行され、適切な解決策ではないことが判明した何かを誤って再試行しないようにします（これは、たとえばコードリファクタリングセッションで発生する可能性があります）。
「デザインB」を実現するコードの目立つ場所にコメントとして書き留めます！
どの場所を選択するかは、特定の状況、これがどの機能であるか、「デザインB」が何を意味するか、周囲のコードベースと比較した場合の大きさ、およびコードベースの構造によって異なります。そうかも知れない
- いくつかの機能のトップ、
- クラスのトップ、または
- モジュールの「readme」ファイル、または
- 特定の設計文書、
チームが好むドキュメントや、システムや組織が持つドキュメントの標準に最も適合する、どんなドキュメントでも。
これについては、リファクタリングセッションなど、見落とされにくい場所を見つけることをお勧めします。また、コードベース自体と一緒にバージョン管理および保守する必要があります。そのため、VCSのコミットメッセージや外部Wikiなどのように、コード外のどこかにのみ文書化するべきではありません。
自己文書化コードは問題ありませんが、高レベルの設計決定には常に高レベルの記述が必要であり、それを回避する方法はありません。そしてコード内のコメントはまさにこれのためです-特定の決定の背後にある明白でないものと理由を文書化するためです。