「読みやすいコードを書く技術」読書メモ

はじめに

この本は、より良いコードを書くのに役立つように設計されています

第 1 章 コードは理解しやすいものである必要があります

コードを「より良く」するもの

可読性の基本定理

コードは、他の人が理解するのにかかる時間を最小限に抑える方法で記述する必要があります

小さいほうが常に良いのでしょうか?

コードを理解するのに必要な時間を最小限に抑えることがより良い目標です

コードを理解するのに必要な時間が他の目標と矛盾するかどうか

まったくやり取りがありません

最も難しい部分

他の人があなたのコードを理解しやすく、余分な時間が必要かどうかを常に考えてください

パート 1 表面レベルの改善

適切な名前を選択し、適切なコメントを書き、より適切な形式でコードをきちんと記述します

第 2 章 名前に情報を入れる

専門的な言葉を選択してください

その機能を用語的に区別し、より表現力豊かな言葉を見つけます

tmpやrevealなどの一般的な名前は避けてください

適切な名前は、変数の目的または変数が持つ値を説明する必要があります

tmp、lt、retval などの一般的な名前を使用する必要がある場合は、十分な理由が必要です

抽象的な名前を具体的な名前に置き換えます

変数、関数、その他の要素に名前を付けるときは、抽象的ではなく、より具体的に説明してください

名前にさらに情報を追加します

変数について読者が知っておくべき重要な点がある場合は、名前に追加の「単語」を追加する価値があります。

単位付きの値、追加の重要な属性

名前の長さはどのくらいにする必要があります

名前は長すぎてはなりません

短い名前は狭い範囲で使用できます

長い名前を入力しても問題ありません (エディターの「単語補完」機能)

頭字語と略語

無駄な言葉は捨てましょう

意味を伝えるために名前の形式を使用します

CamelCase クラス名、アンダースコア メソッド名、定数 CamelCase と kConstant プレフィックス、マクロはすべて大文字とアンダースコア、コンストラクターの最初の文字は大文字、jQuery オブジェクトの前には $

大文字、下線などを意図的に使用します

第 3 章 紛れもない名前

「この名前は他の人によって別の意味を持つものとして解釈されるだろうか?」と何度か自問してください。

例: Filter()

曖昧な言葉で、「選ぶ」という意味なのか「引く」という意味なのかわかりません

例: Clip(text,length)

曖昧な単語は末尾から削除するか、最大長の段落を切り取る場合があります

含まれる範囲を示すために最初と最後を使用することをお勧めします

制限に名前を付ける最も明確な方法は、制限したいものの前に max または min を追加することです。

包含/除外範囲を示すには begin と end を使用することをお勧めします

ブール値に名前を付けます

ブール値を返すブール変数または関数の名前を選択するときは、true と false を返す意味が明確であることを確認してください。

反意名の使用は避けるのが最善です。 「disable_ssl」など。

ユーザーの期待に応える

名前によっては、たとえそれが意図したものではなくても、ユーザーがその意味について先入観を持っているため、誤解を招く可能性があります。この場合、その名前をやめて、誤解を招きにくい名前を使用することをお勧めします。

例: 複数の名前の代替案を比較検討する方法

それぞれの代替名を分析し、誤解の可能性を考慮します。

第4章 美学

コードを読みやすくするには、次の 3 つの原則があります。

。読者がスタイルにすぐに慣れるように、関連するコード行をコード ブロックにグループ化します。

をアルファベット順に並べ替えます。

コメントはコンパクトに保ちます

曖昧な代名詞の使用を避ける

あれ、これ

ラフな文章を磨きます

関数の動作を正確に説明します

このファイル内の行数を返し、ファイル内に改行バイト ('n') が何バイトあるかをカウントします

入出力の例を使用して特殊な状況を説明します

例

コードの意図を説明します

やりたいこと

「名前付き関数パラメータ」に関するコメント

デフォルトパラメータ Connectc(timeout = 10, user_encryption = false)

それができない場合は、Connet(/* timeout_ms= */ 10, /* use_encryption = */ false) を使用してください

情報量の多い単語を使用する

コメントが長すぎると感じる場合は、一般的なプログラミング シナリオを使用してコメントを説明できるかどうかを確認してください

パート 2 ループとロジックの単純化

コード内の「思考の荷物」を最小限に抑えるようにしてください

第 7 章では制御フローが読みやすくなっています

条件、ループ、その他の変更を加えて、フローをできるだけ「自然に」制御します。読者がコードを止めて読み直す必要がないようなメソッドを使用してください

条件文内の参照の順序

比較の左側は、比較の右側の「クエリされた」式であり、比較に使用される常に変化する式に傾きがあり、その値は定数に傾きます

if/else ステートメントブロックの順序

。負論理ではなく正論理の場合を最初に処理します。たとえば、if(!debug) の代わりに if(debug) を使用します。 . まず単純なケースを取り除きます。このアプローチにより、if と else が画面上に表示されるようになり、興味深い状況や疑わしい状況を最初に処理できるようになります

?:条件式 (「三項式」とも呼ばれます)

コード行を最小限に抑えることを追求するのではなく、より良い指標は、人々がコードを理解するのにかかる時間を最小限に抑えることです。

デフォルトでは if/else を使用します。三項演算子?: 最も単純な場合にのみ使用します

do/while ループを避ける

私の経験では、do ステートメントはエラーと混乱の原因です...私は条件文を「目に見えるところに前に置く」傾向があります。その結果、私は do ステートメントの使用を避ける傾向があります。

関数から早期に戻ります

悪名高いgoto

Goto は避けるべきです

ネストを最小限に抑える

深くネストされたコードは理解しにくい

コードに変更を加えるときは、新しい視点からコードを見て、全体を見てください

早めに戻ることで巣作りを減らします

実行プロセスを理解できましたか?

コード内で「スレッド」、「セマフォ」、「例外」、「関数ポインターと匿名関数」、および「仮想メソッド」を多用しすぎて、実装プロセスが高度になり、理解しにくくなる場合があります。

第 8 章 非常に長い式の分割

長い表現を理解しやすいように小さな部分に分割します

説明に使用した変数

一時中間変数

要約変数

ド・モルガンの定理を使用する

それぞれ、否定、変換、および/または

短絡ロジックの悪用

「賢い」小さなコードには注意してください。後で読む他の人にとって混乱を招く傾向があります。

例: 複雑なロジックとの戦い

struct Range{    int begin;    int end;    //For example,[0,5) overlaps with [3,8)    bool OverlapsWith(Range other);}

反対の比較

bool Range::OverlapsWith(Range other){    if(other.end <= begin) return false;    if(other.begin >= end) return false;    return true;}

巨大なステートメントを分割

共通部分を抽出し、集計変数として関数に入れる

式を簡素化する別の創造的な方法

マクロを定義する

第 9 章 変数と可読性

変数が増えるほど、それらすべてを追跡するのが難しくなります

変数のスコープが大きいほど、その動きを追跡するのに時間がかかります

変数が頻繁に変更されるほど、その現在の値を追跡するのが難しくなります

変数を減らす

値のない一時変数

中間結果を削減

制御フロー変数を減らす

変数の範囲を狭める

変数を可能な限り少ないコード行で表示できるようにします。

変数は一度だけ書き込んだ方が良い

変数を操作する場所が増えるほど、その現在の値を判断するのが難しくなります。

最後の例

パート 3 コードを再構成する

関数レベルでのコードへのより大きな変更

第 10 章 無関係な部分問題の抽出

関数またはコードのブロックを見て、このコードの高レベルの目標は何なのかを自問してください。

コードの各行について、「それは目標に向かって直接的に機能しますか?」と尋ねます。このコードの大まかな目標は何ですか?

十分な関数が無関係な部分問題を解決する場合は、コードを独立した関数に抽出します。

一般的なコードとプロジェクト固有のコードを分離する

導入例: findClosestLocation()

純粋なツールコード

その他の多目的コード

サブコード自体を呼び出すと、サブコードの改善が容易になります

共通のコードをたくさん作成する

共通コードが優れているのは、「プロジェクトの残りの部分から完全に切り離されている」ためです。

プロジェクト固有の機能

既存のインターフェースを簡素化する

最適ではないインターフェイスに決して妥協すべきではありません

オンデマンドでインターフェイスを再形成します

多すぎても十分ではありません

分割が細かすぎて、小さな機能が複数あると読みにくくなります

第 11 章 一度に 1 つのことを行う

コードは、一度に 1 つのことを実行できるように編成する必要があります。

タスクは小さくても構いません

投票の例

オブジェクトから値を抽出します

より大きな例

第 12 章 アイデアをコードに変換する

おばあちゃんに説明できないことは、それを本当に理解していないということです。

ロジックを明確に説明します

自然言語でロジックを説明する

関数ライブラリを理解すると役立ちます

洗練されたコードを書くことの一部は、ライブラリが提供するものを理解することです。

このアプローチをより大きな問題に適用してください

自然言語はロジックを記述し、それ自体を適切に再帰的に呼び出します

第 13 章 レスコード

読むのに最適なコードはコードなしです

その機能はわざわざ実装する必要はありません - 必要ありません

質問してニーズを分割してください

コードベースは小さく保ちます

コードベースを可能な限り小さく軽量にしてください

無駄なコードを削除

あなたの周りの図書館についてよく知りましょう

時々、15 分かけて標準ライブラリ内のすべての関数/モジュール/型の名前を読んでください

成熟したライブラリでは、コードの各行が多くの設計、デバッグ、書き換え、ドキュメント化、最適化、テストを表します。

例: コードを記述する代わりに Unix ツールを使用する

次のような新しいコードの作成は避けてください:

。プロジェクトから不要な機能を削除し、過剰なデザインをしないでください。

。要件を再考し、仕事が完了する限り、最も単純なバージョンの問題を解決します。

。標準ライブラリの API 全体を定期的に読んで、よく理解してください。

パート 4 選択されたトピック

第 14 章 テストと可読性

テストを読みやすく、保守しやすくする

他のプログラマーが快適に変更したり追加したりできるように、テストは読み取り可能である必要があります

このテストのどこが間違っているのか

このテストを読みやすくします

より重要な詳細が目立つように、重要でない詳細をユーザーから非表示にします

最小限のテスト宣言を作成します

ほとんどのテストの基本的な内容は、「このような入力/出力状況では、このような動作/出力が期待される」というものに絞り込むことができます

カスタマイズされた「マイクロ言語」を実装する

エラーメッセージを判読できるようにする

エラーを表示するライブラリについて学習します

手作りのエラー メッセージ

エラー メッセージはできる限り役立つものである必要があります

適切なテスト入力を選択してください

基本原則は、テスト対象のコードを完全に使用できる最も単純な入力セットを選択する必要があるということです

シンプルで仕事を完了させるテストの方が価値があります

1 つの関数に対する複数のテスト

テスト関数に名前を付けます

テスト__()

そのテストには何か問題があります

テストのためのより良い開発方法

テストしやすいコードの作成を開始します。

行き過ぎです

。テストを可能にするためだけに実際のコードの可読性を犠牲にします。テストが製品開発の障害になるようにします。

第 15 章「分/時カウンター」の設計と改善

質問

過去 1 分および 1 時間に Web サーバーが転送したバイト数を追跡​​します。

クラスインターフェースを定義

試み 1: 素朴な解決策

トライ 2: コンベア ベルトの設計

トライ 3: タイム バケットの設計

3 つのオプションを比較します