コーヒーブレイク#103。「クリーンコード」を守るために: 時代を超えた 100 のヒント

出典: Hackernoon ロバート C. マーティン著「クリーン コード」は、史上最も推奨されるプログラミング本です。「ソフトウェア開発者向けのベストブック」というクエリを使用して書籍を検索すると、ほぼ確実にこの書籍が検索結果に表示されます。クリーンコードには注目する価値がないと感じる人もいますが、私はそのような感情は大きな間違いであると主張します。はい、この本のアドバイスの中には疑わしいものもあります。はい、一部のコンテンツは古いようです。はい、いくつかの例は混乱を招きます。それはすべて本当です。ただし、この本が提供する多くの有益なヒントをすぐに軽視しないでください。いくつかの悪いアイデアがあるからといって、クリーン コードを完全に無視することは、最善の解決策ではありません。 それでは、さっそく、クリーン コードが提供する最高のヒントを見てみましょう。各章を読み進めて、ボブおじさんとその共著者が提案するアイデアを要約していきます。

第 1 章: クリーンなコード

1. 散らかった全体の量は時間の経過とともに増加します。

2. 古くなったシステムを最初から復元するのは非常に困難です。これには、リファクタリングと段階的な改善が最適なオプションです。

3. 乱雑なコードベースでは、数時間しかかからないはずのタスクが完了するまでに数日、または数週間かかる場合があります。

4. 時間をかけて迅速に行動しましょう。

5. クリーンなコードは 1 つのことをうまく機能させます。悪いコードは過剰な処理を試みます。

6. クリーンなコードは十分にテストされています。

7. うまく書かれたコードを読むと、各関数はおおよそ期待どおりの動作をします。

8. 長年の経験を持つ人が教えた原則に同意できない場合は、それを無視する前に、少なくともその人の視点を考慮する必要があります。

9. コードは書かれるよりも読まれる方がはるかに頻繁です。

10. コードは読みやすく、変更も容易です。

11. コードベースは見つけたときよりも良い状態で残しておきます (ボーイスカウトのルール)。

第 2 章: 名前の意味

1. 変数名は慎重に選択してください。

2. 良い名前を選ぶのは難しいです。

3. 変数または関数の名前は、それが何であるか、またどのように使用されるかを示す必要があります。

4. ループ内のカウンタ変数の i など、一般的に使用される名前を除き、単一文字の変数名は使用しないでください。

5. 変数名には省略形を使用しないでください。

6. 変数名について話したり、声に出して言えるように、変数名は発音できる必要があります。

7. 見つけやすい変数名を使用してください。

8. クラスとオブジェクトには名詞の形式の名前が必要です。

9. メソッド名と関数名は、動詞または動詞と名詞のペアである必要があります。

第 3 章: 機能

1. 関数は小さくなければなりません。

2. 関数は 1 つのアクションを実行する必要があります。

3. 関数にはわかりやすい名前が必要です。

4. if/else 本体のコードを抽出するか、ステートメントを明確に名前が付けられた関数に切り替えます。

5. 関数が取る引数の数を制限します。

6. 関数に多くの構成引数が必要な場合は、それらを 1 つの構成パラメーター変数に結合することを検討してください。

7. 関数は純粋である必要があります。これは、関数に副作用がなく、入力引数を変更しないことを意味します。

8. 関数はコマンドまたはクエリである必要がありますが、両方を同時に使用することはできません (コマンド クエリ分離)。

9. コードにエラーを残すよりも、コードからエラーと例外を削除する方が良いでしょう。

10. 重複したコードを明確に名前が付けられた関数に抽出します (繰り返さないでください)。

11. 単体テストにより、リファクタリングが容易になります。

第 4 章: コメント

1. コメントは間違っている可能性があります。最初から間違っている可能性もあれば、最初は正確でもコードが変更されるにつれて時間の経過とともに古くなってしまう可能性もあります。

2. コメントを使用して、何が起こっているのかを説明するのではなく、なぜそのように書かれているのかを説明します。

3. 多くの場合、明確に名前が付けられた変数を使用し、コードのセクションを明確に名前が付けられた関数に抽出することで、コメントを回避できます。

4. TODO コメントの先頭に一貫した接頭辞を付けて、見つけやすくします。TODO コメントを定期的に確認してクリーンアップします。

5. Javadoc を使用するためだけに使用しないでください。メソッドの動作、メソッドが受け取る引数、およびメソッドが何を返すかを説明するコメントは、良く言えば冗長で、悪く言えば誤解を招きます。

6. コメントには、読者が必要とするすべての関連情報とコンテキストを含める必要があります。コメントを書くときは怠惰にしないでください。

7. バージョン管理と git 責任により、ログ コメントとファイル作成者のコメントは必要ありません。

8. デッドコードをコメントアウトしないでください。削除してください。将来そのコードが必要になると思われる場合、それがバージョン管理の目的です。

第 5 章: フォーマット

1. チームとして、コードをフォーマットするための一連のルールを選択し、それらのルールを一貫して適用します。どのようなルールに同意するとしても、合意に達する必要があります。

2. 自動コードフォーマットとコードアナライザーを使用します。すべての書式設定エラーを手動で見つけて修正するのに人に頼らないでください。これは非効率的で非生産的であり、コードをレビューする際の時間の無駄です。

3. コードの行間に垂直方向のスペースを追加して、関連するコード ブロックを視覚的に分離します。必要なのは、グループ間に新しい行を 1 行作成することだけです。

4. 小さなファイルは、大きなファイルよりも読みやすく、理解しやすく、移動しやすいです。

5. 変数は、使用される場所の近くで宣言する必要があります。小さな関数の場合、これは通常関数の先頭にあります。

6. 短い関数や if ステートメントの場合でも、1 行で記述するのではなく、正しくフォーマットしてください。

第 6 章: オブジェクトとデータ構造

1. オブジェクトの実装の詳細は、オブジェクトのインターフェイスの背後に隠す必要があります。オブジェクトのコンシューマーが使用するインターフェイスを提供すると、破壊的な変更を引き起こすことなく、後で実装の詳細をリファクタリングすることが容易になります。抽象化によりリファクタリングが容易になります。

2. 特定のコード部分は、それが操作するオブジェクトの内部についての知識を持たないでください。

3. オブジェクトを操作するときは、オブジェクトの内部について尋ねるのではなく、オブジェクトにコマンドまたはクエリの実行を要求する必要があります。

第 7 章: エラーの修正

1. エラー処理は、モジュール内の残りのコードに干渉してはなりません。

2. コードにエラーを残すよりも、コードからエラーと例外を削除する方が良いでしょう。

3. エラーを含むテストを作成して、コードがエラーを識別し、見逃さないことを確認します。

4. エラー メッセージは、効果的なトラブルシューティングに必要なすべてのコンテキストを含む有益な情報である必要があります。

5. サードパーティ API を抽象化の薄い層でラップすると、将来、あるライブラリを別のライブラリに簡単に置き換えることができます。

6. サードパーティ API を抽象化の薄い層でラップすると、テスト中にライブラリをモックすることが簡単になります。

7. 特定のデータが存在しない場合など、例外的な動作を処理するには、Special Case パターンまたは Null Object パターンを使用します。

第 8 章: 境界

1. サードパーティのライブラリを使用すると、さまざまなタスクをアウトソーシングできるため、製品の配信が迅速化されます。

2. サードパーティのライブラリを正しく使用していることを確認するテストを作成します。

3. アダプター パターンを使用して、サードパーティ ライブラリの API と必要な API の間のギャップを埋めます。

4. サードパーティ API を抽象化の薄い層でラップすると、将来、あるライブラリを別のライブラリに簡単に置き換えることができます。(第 7 章からの繰り返し)

5. サードパーティ API を抽象化の薄い層でラップすると、テスト中にライブラリをモックすることが簡単になります。(第 7 章からの繰り返し)

6. サードパーティのライブラリの詳細について、アプリケーションにあまり多くの情報を伝えないようにしてください。

7. 自分がコントロールできないものに依存するよりも、自分がコントロールできるものに依存する方が良いのです。

第 9 章: 単体テスト

1. テスト コードは実稼働コードと同じくらいクリーンである必要があります (通常はメモリまたは効率に関連するいくつかの例外を除きます)。

2. 実稼働コードが変更されると、テストコードも変更されます。

3. テストは、実稼働コードの柔軟性と保守性を維持するのに役立ちます。

4. テストを使用すると変更を加えることができるため、自分で気づかないことを恐れることなく、自信を持ってリファクタリングできるようになります。

5. Arrange-Act-Assert (Build-Operate-Check、Setup-Exercise-Verify、または Given-When-Then とも呼ばれる) パターンを使用してテストを構造化します。

6. ドメイン固有の関数を使用して、テストの作成と読み取りを容易にします。

7. テストごとに 1 つのコンセプトを採点します。

8. テストは高速でなければなりません。

9. テストは独立している必要があります。

10. テストは再現可能でなければなりません。

11. テストでは確認を必要とすべきではありません。

12. テストは、数か月後ではなく、実稼働コードが作成される直前または直後に適時に作成する必要があります。

13. テストが悪い場合は、コードにバグがあることが予想されます。

第 10 章: クラス

1. クラスは少人数である必要があります。

2. クラスは 1 つのことに対してのみ責任を負う必要があり、変更する理由も 1 つだけである必要があります (単一責任原則)。

3. クラスに明確な名前を思いつかない場合は、おそらく大きすぎます。

4. コードを動作させるだけで仕事が終わるわけではありません。次のステップは、コードをリファクタリングしてクリーンアップすることです。

5. アプリケーション内でいくつかの大きなクラスの代わりに多くの小さなクラスを使用すると、開発者が特定のタスクに取り組むときに理解しなければならない情報の量が減ります。

6. 優れたテスト スイートを使用すると、大きなクラスを小さなクラスに分割するときに自信を持ってリファクタリングできます。

7. クラスは拡張の場合はオープンですが、変更の場合はクローズされる必要があります (オープンクローズの原則)。

8. インターフェイスと抽象クラスは、テストを容易にする継ぎ目を作成します。

第 11 章: システム

1. 依存関係の注入を使用すると、開発者は適切なインターフェイスを持つ任意のオブジェクトを別のクラスに渡すことができる柔軟性が得られます。

2. 依存関係の注入を使用してアプリケーション内のオブジェクト間のインターフェイスを作成し、テストを容易にします。

3. ソフトウェア システムは、事前に設計する必要がある建物のようなものではありません。これらは、現在のニーズに適応しながら、時間の経過とともに成長し、拡大していく都市に似ています。

4. 最後の重要な瞬間まで決定を延期します。

5. ドメイン専門家と開発者が同じ用語を使用できるように、ドメイン固有の言語を使用します。

6. システムを過度に複雑にしないでください。機能する最も単純なものを使用してください。

第 12 章: 導入

1. テストできないシステムは検証できません。また、検証できないシステムは決して導入すべきではありません。

2. テストが簡単なコードでは依存関係の挿入、インターフェイス、抽象化がよく使用されるため、テストを作成すると設計が改善されます。

3. 適切なテスト セットを使用すると、リファクタリング中にアプリケーションが壊れるという心配がなくなります。

4. コードを複製すると、コード内に変更できる箇所がさらに多くなり、エラーが隠蔽される可能性がある箇所がさらに増えるため、より多くのリスクが生じます。

5. ここで作成するコードは、コードの理解に深く関わっているため、理解しやすくなります。他の人がすぐに同じレベルの理解に達するのは簡単ではありません。

6. ソフトウェア プロジェクトのコストのほとんどは、長期的なメンテナンスに関連しています。

7. テストは、アプリケーションがどのように動作するか (実際にどのように動作するか) を示す生きたドキュメントとして機能します。

8. コードが機能したら、それ以上先に進まないでください。時間をかけて、より明確でわかりやすいものにしてください。

9. 近い将来、次にあなたのコードを読む人は、おそらくあなたです。理解しやすいコードを書いて、将来の自分に優しくしてください。

10. 教義に抵抗してください。プラグマティズムを受け入れましょう。

11. 本当に優れたソフトウェアエンジニアになるには何十年もかかります。周りの専門家から学び、一般的に使用されるデザイン パターンを学ぶことで、学習曲線を短縮できます。

第 13 章: 並列処理

1. 並列コードを書くのは難しいです。

2. 時折発生する再現が難しいバグや問題は、多くの場合同時実行性の問題です。

3. テストはアプリケーションにバグがないことを保証するものではありませんが、リスクは最小限に抑えられます。

4. 一般的な同時実行の問題とその考えられる解決策について学びます。

第 14 章: 逐次改良

1. クリーンなコードは通常、白紙の状態から始まるわけではありません。まず大まかなソリューションを作成してから、それをリファクタリングしてよりクリーンなものにします。

2. コードが動き始めたら、その作業をやめるのは間違いです。すでに機能している後は、時間をかけてさらに改善してください。

3. 不安は徐々に拡大している。

4. 機能の追加が難しすぎる、または時間がかかりすぎるという状況に陥っている場合は、機能の作成を中止してリファクタリングを開始してください。

5. 多くの場合、最初から再構築するよりも段階的な変更の方が優れています。

6. テスト駆動開発 (TDD) を使用して、非常に小さな変更を多数加えます。

7. 優れたソフトウェア設計には、コード内の関心事項を分離し、コードをより小さなモジュール、クラス、ファイルに分割することが含まれます。

8. 後で片付けるよりも、作った直後に散らかった汚れを片付けるほうが簡単です。

第 15 章: JUnit の内部構造

1. 負の変数名や条件式は、正の変数名や条件式に比べて理解するのが少し難しくなります。

2. リファクタリングは、試行錯誤を繰り返す反復的なプロセスです。

3. コードベースは見つけたときよりも良い状態で残しておきます (ボーイスカウトのルール)。（第1章より再掲）

第 16 章: SerialDate のリファクタリング

1. コードレビューやコードの批判は私たちをより良くしてくれますし、それは歓迎すべきです。

2. まずコードを動作させてから修正します。

3. コードのすべての行をテストする必要があるわけではありません。

第 17 章: 匂いとヒューリスティック

1. クリーンなコードは一連のルールではなく、むしろ作業の品質を決定する価値体系です。

[この章では、ボブおじさんはコードとヒューリスティックのさらに 66 のバリエーションを列挙しており、その多くは本書の残りの部分で取り上げられています。ここで再現すると、各項目の名前をコピペすることになるので、控えさせていただきました。代わりに本を読むことをお勧めします！]

結論

始めたところで終わりにしましょう。Robert C. Martin 著の『Clean Code』は、史上最も推奨されるプログラミングの本です。これには十分な理由があります。