クリーンコード：ネーミング

投稿日: 2022-11-04 2022-11-11
タグ: Programming

1. 序章

このチュートリアルでは、ネーミングについて見ていきます。 ネーミングは、あらゆるプログラミング言語の開発者にとって重要で日常的なタスクです。コードを理解するのが非常に難しくなるか、うまくいけば理解しやすくなります。私たちが書くコードのすべての詳細には、名前、関数、クラス、変数などがあります。ネーミングの目標をより深く調べることから始めましょう。その後、いくつかのすべきこととすべきでないことを探ります。

2. ゴール

名前は主に開発者によって使用されます。これらの名前は内部的なものである可能性がありますが、APIの一部である可能性もあります。その場合、聴衆はさらに広くなります。また、商用プロジェクトの場合、ソフトウェアの存続期間中、社内の開発者でさえ幅広い個人が含まれる可能性が高いことにも注意してください。

高齢性には大きな違いがあるだけでなく、文化的背景にも違いがある可能性があります。新しい名前を選ぶときは、常にそれを覚えておく必要があります。

コードがストーリーを伝えるのを助けるために名前を使用します。関連する名前を省略すると、次のコードが実際に何をしているのかがわかりにくくなります。

function applies(e: Evnt) {
    if (e.d == 6 || e.d == 0) {
         return false;
    } else {
        return (e.t.h >= 8 && e.t.h < 18); 
    }
}

あまり時間をかけずに、コードが何をするのかがわかりますが、なぜそれが行われるのでしょうか。どういう意味ですか？同じコードの断片を見てみましょう。ただし、この例にはより適切な名前があります。

function isDuringWorkingHours(event: Event) {
    if (event.dayOfWeek == DayOfWeek.SATURDAY || event.dayOfWeek == DayOfWeek.SUNDAY) {
         return false;
    } else {
        return (event.time.hour >= WORKING_DAY_START && event.time.hour < WORKING_DAY_END); 
    }
}

行った変更を見てみましょう。まず、メソッドにわかりやすい名前を付けることから始めました。次に、フィールド d を置き換えました。これは、すべてをより特徴的な用語dayOfWeekに置き換えることができます。次に、曜日を表す定数を抽出しました。最後に、5行目でも同様の変更を加えました。

この例を振り返ると、適切な名前がコードの意味を理解するのに役立つことがわかります。次のセクションでは、命名に関するいくつかのベストプラクティスを見ていきます。

3. 標的

名前は明確でわかりやすいものでなければなりません。また、驚き最小の原則に焦点を当てる必要があります。したがって、他の人が期待するコードを作成し、驚かないようにすることを目指しています。そうすれば、次の人は物事がどこにあるのか、そしてそれらが何を意味するのかを簡単に推測することができます。

私たちが選択する名前は開発者を対象としていることはすでに説明しました。したがって、これは、他の人もシングルトンとは何か、またはビジターパターンとは何かについての考えを持っていると安全に想定できることを意味します。したがって、一般的に、適用する場合はソリューションドメインの概念を使用することを好みます。 これにより、コミュニケーションがはるかに簡単になります。

独自のドメインに明確で特徴的な名前が存在しない場合、次善の策はビジネスドメインを使用することです。したがって、プロセスの名前を作成する代わりに、ビジネスの既存のプロセスを使用します。これにより、開発者間のコミュニケーションだけでなく、開発者とビジネス間のコミュニケーションも改善されます。

3.1. 検索可能

目標についてのセクションですでに示したように、非常に短い名前を使用すると、コードの可読性が損なわれます。もう1つの欠点は、コードで短い名前を検索するのが難しいことです。定数の使用についても同じことが言えます。

前のセクションのコードを更新して、土曜日を営業日として含める必要がある場合を検討してください。 SATURDAY、を検索できる例では、誤検知が少なくなります。または、IDEを使用して、SATURDAY定数の使用状況を検査することもできます。

3.2. 1つのこと–1つの言葉

同じもの/アクションを参照するときは、必ず同じ用語を再利用してください。したがって、1つのフィールドの名前 address を選択するときは、同じ名前を同じものに使用する必要がありますアプリケーション全体の概念。同じことがメソッドにも当てはまります。たとえば、さまざまな種類のオブジェクトに要素を追加する場合、それが同じ操作である場合は、一貫して同じ名前を使用するようにします。

しかし、これは名前が石に設定されているという意味ではありません。結果として適用できる、より一致する名前が見つかった場合はいつでも、リファクタリングする瞬間になる可能性があります。

ただし、2つのものが完全に同じでない場合は、それらをそれぞれの名前で適切に区別する必要があることに注意してください。

3.3. 発音可能

ネーミングはコミュニケーションがすべてです。したがって、選択した名前を発音しなければならない可能性があります。これは、誰かを指導したり、コードレビューを行ったり、厄介なバグを追跡していることが原因である可能性があります。

しかし、その瞬間に私たちが選んだ名前のためにコミュニケーションが取れない場合、私たちは仕事をすることができませんでした。ですから、常に私たちが伝えられる名前を使うことを目指してください。

3.4. 命名基準に従う

最後に、一般的に受け入れられている標準がいくつかあります。まず、クラス名には、CarやDuckなどの名詞を使用する必要があります。 一方、メソッドの場合は、動詞または動詞句を使用する必要があります。多くの場合、1つの動詞では自分自身を表現するのに十分ではないためです。その例としては、applyRegulationsまたはcalculateTaxesがあります。

4. 避ける

前のセクションでは、私たちが目指すいくつかのことを提案しました。このセクションでは、むしろ避けているいくつかのプラクティスに焦点を当てます。

4.1. 偽情報

偽情報には多くの種類があり、ほとんどが意図的ではありません。たとえば、マイナーなリファクタリングの結果として、コードが偽情報を提供してしまう可能性があります。

たとえば、次のフラグメントを参照してください。

Set<Address> addressList = person.getAddresses();

上記の変数の名前にはListが含まれていますが、は実際にはSetです。異なる言語のバックグラウンドを持つ人々にとって、結果として重複するエントリは無視されるため、一部の追加操作は、純粋に名前に基づいて期待することを実行しません。この場合、Listという単語を省略してaddressesと呼ぶのが最も理にかなっているかもしれません。

他の形式の偽情報は、変数内のノイズワードである可能性があります。 データ、プロセッサ、テーブル、情報などの単語は非常に一般的に使用されているため、有用な区別はありませんほとんどのメソッドまたは変数は、情報またはその処理と関係があるためです。

4.2. エンコーディングを避ける

初期のプログラミング言語またはそのベストプラクティスでは、正確な型に関するヒントが必要でした。ただし、今日のプログラミング言語では、これらの型のヒントは必要ありません。コンパイラ/IDEがこれを処理してくれるので、それらを省略しましょう。また、タイプが後でリファクタリングされることもよくあるので、次のフラグメントのように、コードが誤った情報を伝播するのは残念です。

ZipCode zipCodeString = new ZipCode("1974XA")

他のエンコーディングには、変数または同様のエンコーディングの特定の名前を含めることができます。これが必要でない場合、またはその言語での一般的な慣習である場合は常に、これに反対することをお勧めします。その場合、名前をニュートラルで機能的なものにすることを常にお勧めします。

4.3. スラング

追加のコンテキストをあまり必要とせずに、できるだけ明確にすることを目指します。特にスラングやジョークを使用しても、長期的にはメリットがありません。 buttonSmashHandler は、初めて見たときは楽しいかもしれませんが、buttonClickHandlerと呼ぶ方がよいでしょう。

4.4. メンタルマッピングを避ける

コードの読者を驚かせないことを目指しています。これは、1文字の変数が許可されているが、特定の場所でのみ許可されていることを意味します。したがって、ループ変数にiまたはjを使用しても驚くことではありません。ただし、他のコンテキストではこれらの名前を使用しない方がよいでしょう。

ソリューションドメイン、つまりソフトウェアドメインの名前を使用することを好むことはすでに説明しました。ただし、これは、意味が異なる名前や頭字語を使用する場合は注意が必要であることを意味します。したがって、顧客であるユーザーをモデル化する場合は、オブジェクトをVisitorと呼ぶことを再検討してください。これは頭字語にも当てはまります。idを使用してinside d iameterを参照すると、多くの開発者を混乱させます。

4.5. 一言一言

同じものに同じ言葉を使うことの重要性をすでに強調しました。ただし、その逆がさらに重要になる場合があります。 同じ概念を参照していない場合は、同じ単語を使用しないでください。したがって、アプリケーションが木製のマッチに一致する場合は、話しているときに明確にするために余分な時間を費やす可能性があります。マッチングのプロセス、成功したマッチ、そして木製のマッチについて。

より一般的なシナリオは、多くのメソッドにすでにaddメソッドがある場合です。ここにもアイテムを追加しますが、特定の場所を追加したり、既存のデータを置き換えたり上書きしたりするなど、特性が異なる場合。次に、それが別の操作であることを明確にすることが重要であり、独自の名前を付ける必要があります。

4.6. 名前はコメントを必要としないはずです

コメントに関する記事ですでに取り上げたように、名前にはコメントは必要ありません。代わりに、コメントの必要性を排除するために使用する必要があります。次の2行のコードを比較してみましょう。1つはコメント付きで、もう1つは名前が改善されています。

int timeout = 5; // timeout in seconds
int timeoutInSeconds = 5;

些細なコメントを追加することになったときは、それを追加するための代替案について常に考えてみてください。

4.7. 頭字語に注意してください

すでに述べたように、頭字語を名前として使用する場合は注意が必要です。それらは異なる意味を持つことができるだけではありません。さらに、異なる第一言語または異なる文化的背景を持つ人々にとって、コードが理解しにくくなる可能性があります。したがって、頭字語は非常に一般的であり、代替手段が不十分な場合にのみ使用してください。 しかし、一般的には、頭字語を綴るだけを好みます。

5. 結論

この記事では、名前を付けるためのいくつかのベストプラクティスと、避けるべきいくつかのプラクティスについて説明しました。ネーミングは私たちの日常業務の大きな部分であるだけでなく、非常に重要なタスクでもあることがわかりました。それはコードを平均的または優れたものにすることができます。

getdocs

13036