開発初期は「とりあえず早く動くものを作る」ことがよしとされることが多い。
場合によってはお客様に提供が始まってからも、「とりあえず早く動くものを作ろう」精神で進めることもある。
しかし、シチュエーションは変わるのである。経験的にこの2つが大きな変数になると感じている。
お客様が使い始めている
他の開発者（や他の開発メンバー）がチームに加わっている
"お客様が使い始めている"こと
とてもハッピーなことだ。最初に作ったものが受け入れられて、ファンができたわけである。C向けのアプリでもB向けの業務アプリでも、誰かの行動を支えて（変えて）いるわけである。
この時、「とりあえず早く動くものを作る」には、「今のユーザの体験・データを壊さずに」という条件がつく。
つまり、今まで自由にビルドアンドスクラップしていたところが変わるのである。継続的に使ってもらい続けながら、互換性を保ちながら（時には破壊的に）アップデートし続ける必要があるのである。
この時に必要となってくるのは、テストとリファクタリングである。
テストはなんとなくイメージがつきやすい。システムというのは往々にして不具合がある。機能を追加すれば触っていないところが壊れるというのは日常茶飯事だ。それを自動・手動交えながらテストを行なって、品質の低下を妨げるのはおそらく誰にとっても受け入れやすい。
一方でリファクタリングはどうだろう。一見お客様が使い始めていることには直接関係なさそうだ。「動いているソースコードに触るな」という言葉もある。
しかし、特に関係あるのがリファクタリングである。継続的なリファクタリングをしなければ、プログラムの可読性・保守性は落ちる一方で、機能追加のスピードにも影響する。「動いているソースコードに触るな」を言葉通り受け取って、コピペを繰り返していたとしても、不具合があった時は修正箇所が増加する。（テストも含めるとさらに多い）
そう、「とりあえず早く動くものが作れなくなる」のである。全てを壊しながら進めるときと違って、再構築と再設計を繰り返していかないと、継続的なアップデートすらもできなくなっていく。（テストはその継続的なアップデートを再現性高く保証してくれるもの）
”他の開発者（や他の開発メンバー）がチームに加わっている”こと
初期とは違ってメンバーも増えた。最初の苦労を知らないで、自由に色々意見しているかもしれない。（それは良いことだ）
人数が増えたので、開発スピードも上がりそうだ。しかしそうはならない。なぜか、「コードを読む必要」があるからである。
一番初めの頃の「とりあえず動くものを作る」は言葉の通り、クリティカルパスを通りさえすれば良いとされていることが多い。（もちろんその限りではない）
それは例外処理や大量データの処理などを想定しきれていない場合が多い。優れたメンバーであるほど、そのコードに向き合ったとき「ここはどうしてこう書いているんだろう」という疑問が出てくるだろう。（真に優秀であればそのコンテキストすら読み取れるかもしれないが、それを期待するのは再現性がない）
また、動かすために得てして、ハック的な書き方やレイヤーを無視するなどお作法的にはNGな書き方をする場合もある。
コードはその時のコンテキストを保持してくれないのである。
もちろんcommit logを読めば、昔のPRを読めばわかるケースは存在する。しかし、それは本当に「早く作る」ことにつながるだろうか。
「コメント」が必要なのである。ここでいうコメントは、JavaScriptならJSDoc、GoならGoDocのように、コード上に書くコメントである。
コメントはコードの振る舞い以上に意図を表しやすい。テストコードやリファクタリングでも「なぜそうしたか / 今こうできていないか」を表現するのはかなり難しい。コメントを書くことで、コードには表現しきれないコンテキストや負債を「他の人に自然言語で、必要な時に伝えること」ができるのである。
また、私は振る舞い自体を日本語で書くことも非常に良いと思っている。特にユースケース層などと言われる、手続きが書かれている箇所に関しては積極的に「どう動くか」を書いている。
一見アンチパターンのようだが、ユースケースというのは大きく変わることは少ない。仮に大きく変更が必要なのであれば、振る舞いについて例外を含めて再検討する必要があるだろう。その時にコードコメントを最新化することの労力はほぼない。（むしろインターフェースを考えるきっかけですらある）
日本語話者が多いプロジェクトなら積極的に日本語を採用すべきである。ここで大事なことは、振る舞いを日本語で書いて、プログラムを実装することであり、それにテストケースも加わると、今の振る舞いに関して3つのアプローチで記述されることになる。（「仕様の漏れ」に気付きやすいという副次的効果もある）
つまり前述した「コードを読む必要」に対して3通りの読み方を用意できるのである。これによって、新しいメンバー（あるいは未来の自分）が増えたときの伝え方をプロダクションコード自体に残していけるのである。
余談：ドキュメントの置き場所
ドキュメントの置き場所についてだが、私は「コロケーション」の考え方が好きで、できるだけコードの近く（というより中）におきたい派である。
コロケーションについて詳しくはhttps://www.mizdra.net/entry/2022/12/11/203940を参照されたし