Why Code Formatting Matters More Than You Think

私は、セミコロンが見つからなかったために、人生の3時間を失った日のことを今でも覚えています。見つけられなかったからではなく、私は14年の経験を持つシニアソフトウェアアーキテクトですが、私たちのコードベースはフォーマットに関して悲惨な状態で、実際のエラーを追跡するのは、長いカーペットの中でコンタクトレンズを探すようなものでした。それは2019年、名前を明かさないフィンテックスタートアップでのことです。私たちは47人の開発者がいて、フォーマットについての標準はゼロ、230,000行のコードに散らばる「創造的なインデントの選択」としか表現できないものがありました。

その事件は、私たちに製品デプロイの遅延と、約18,000ドルの開発者の時間を費やさせ、コードの品質について私が考える方法を根本的に変える会話を引き起こしました。なぜなら、私が学んだことは、コードフォーマットは美学や開発者のエゴに関するものではなく、認知負荷、チームの速度、そして私たちがフォーマットを考慮外として扱うたびに毎日支払っている隠れた税金に関するものだからです。

一貫性のないフォーマットの認知コスト

まず最初に、多くの開発者が気づいていないことから始めましょう：あなたの脳は、形式が一貫していないコードに出くわすたびに余分な作業をしています。パターン認識に関する神経科学の研究によれば、私たちの視覚野は馴染みのあるパターンを新しいものよりも60%速く処理します。一貫したフォーマットのルールに従ったコードを読んでいるとき、あなたの脳は論理と意図に集中できます。フォーマットが混沌としていると、単に構造を解析するためにメンタルサイクルを消費しています。

昨年、現在の会社で非公式な実験を行いました。私たちは12人の中堅開発者を取り、2つの機能的に同一のコードベースをデバッグさせました—一つは厳格なフォーマット基準を持ち、もう一つは持っていないものです。フォーマットが一貫しているコードは、平均で23分早くデバッグされました。それは大したことのないように思えるかもしれませんが、これをすべてのコードレビュー、すべてのバグ修正、すべてのフィーチャー追加に掛け算してください。30人の開発者のチームの場合、年間で約345時間、つまり生産的な時間の2ヶ月以上がフォーマットの混沌に失われるということです。

認知負荷の問題は、複雑さと共に悪化します。入れ子になった条件文、コールバックチェーン、または複雑なデータ変換を扱う場合、一貫したフォーマットはあなたのライフラインになります。それは、すぐに構造を見るのと、メンタルで再構築する必要があることの違いです。適切なインデントとスペースがあればすぐに明確であった50行の関数を理解するのに、ジュニア開発者が15分も費やしているのを見たことがあります。

そして、ここでの苦痛は、この認知税が累積することです。異なるフォーマットのファイル間でコンテキストスイッチをするたびに、あなたの脳は再調整しなければなりません。一日に何度も左側通行と右側通行を切り替えるようなものです。技術的には可能ですが、疲れるし、ミスも多くなります。

フォーマットの負債の隠れた経済性

お金の話をしましょう、なぜならそれがリーダーシップの注意を引くからです。技術的な負債は良く知られた概念ですが、フォーマットの負債は誰も追跡しない狡猾な従兄弟です。前の会社では、フォーマット基準の欠如が年間約127,000ドルのコストを引き起こしていると計算しました。その数字に到達した経緯を説明します。

"コードフォーマットは美学や開発者のエゴに関するものではなく、認知負荷、チームの速度、そして私たちがフォーマットを考慮外として扱うたびに毎日支払っている隠れた税金に関するものです."

まず、コードレビューの時間。私たちの平均プルリクエストは、レビューに47分かかりました。PrettierとESLintを使って自動フォーマットを導入した後、それは31分に減りました。違いは？レビュアーがスペースの議論、インデントの不一致、または構造が悪いコードの解析に時間を無駄にしていないことです。年間約2,400のプルリクエストで、640時間が節約されました—私たちの平均開発者給与で約64,000ドルです。

次に、オンボーディングの摩擦。新しい開発者は、生産的な貢献者になるまで平均3.2週間かかりました。フォーマットが標準化された後、それは2.4週間に減りました。なぜでしょう？彼らは各開発者の個人的なフォーマットスタイルを解読するのではなく、ビジネスロジックを理解することに集中できたからです。年間8人の新入社員で、それは生産性が6.4週間増加したことになります—約38,000ドルです。

三つ目は、バグの導入率。この点は私を驚かせました。私たちは、変更された1,000行あたりの導入されたバグを追跡していました。コードベースのフォーマットが悪い部分では、1,000行あたり4.7のバグの率がありました。フォーマットが良い部分では、1,000行あたり2.9のバグの率です。相関関係は因果関係ではありませんが、重要です。フォーマットが悪いコードは推論が難しく、より多くのミスを引き起こします。バグを特定し、修正し、確認するのに平均3.5時間かかるとすると、それは重要です。

これらの数字は私たちのコンテキストに特有ですが、パターンは組織全体に当てはまります。フォーマットの負債は実際のもので、測定可能で、高額です。

手動フォーマットが負け戦である理由

私のキャリアの初期に、47ページのスタイルガイドがあった会社で働いていました。ブレースをどこに置くか、変数をどう命名するか、スペースとタブをいつ使うかに関する47ページのルールです。それは包括的で、思慮深く、全く役に立ちませんでした。誰も読みませんでした。誰も従いませんでした。コードレビューは機能性とは無関係なスタイルの議論に終始しました。

手動フォーマットの根本的な問題は、人間の一貫性に依存していることであり、人間は一貫性が苦手です。私たちは創造的で、意見があり、忘れっぽいです。最善の意図を持っていても、開発者は気分、カフェインの量、そして昼食に応じて異なる方法でコードをフォーマットします。同じ開発者が同じファイル中で3つの異なる方法でコードをフォーマットするのを見たことがあります。

手動フォーマットはまた、逆効果のあるインセンティブを生み出します。私は、才能のある開発者が何百行もの再フォーマットに対処したくないためにリファクタリングを避けるのを見てきました。私は、チームがフォーマットのクリーンアップのために多くのファイルに触れなければならないので、重要なアーキテクチャの変更を先延ばしにするのを見てきました。手動でフォーマットされている場合、改善の障壁になります。

コードレビューの問題はさらに悪化します。私は、コードレビューで80%のコメントがフォーマットに関するものであったことがあります。「ここにスペースを追加してください。」「このインデントは間違っています。」「私たちはシングルクオートを使い、ダブルクオートは使いません。」これらの議論は心を痛めます。開発者がマイクロマネジメントされていると感じさせ、皆の時間を無駄にし、実際のコードの品質の問題、つまり論理エラーやセキュリティ上の脆弱性、またはアーキテクチャの問題から注意を逸らさせます。

これらのスタイルの議論は決して解決されません。タブとスペースのどちらが正しいか、またはブレースをどこに置くべきかに客観的な正解はありません。すべて好みです。しかし、コード上で好みについて議論しているとき、