表現力のある名前を作成するための9つのガイドライン

命名は主観的で状況に依存し、それは芸術です。ほとんどの芸術と同様に、私たちはパターンを発見します。私は他人のコードを読むことで多くを学びました。この記事では、他人のコードを読むときに彼らが従ってくれていたらと思う9つのガイドラインをまとめました。

ソフトウェアエンジニアがクラスを開くとき、彼女は名前に基づいて、そのクラスの責任を知るべきです。はい、命名は車輪の一本のスポークに過ぎないことは知っています。物理的および論理的構造もコードの理解に重要な役割を果たしますし、複雑さも同様です。この記事では、命名がコード理解に最も大きな影響を与えると感じるため、命名のみに焦点を当てています。

意図を明確にしない限り、型を含めないでください

型は、プログラミング型（string、int、decimal）から責任のグループ化（Util、Helper、Validator、Event など）まで、あらゆるものになります。多くの場合、それは意図を表現しない分類です。

例を見てみましょう。StringHelper という名前はあまり多くを表現していません。string はシステム型であり、Helper は曖昧です。StringHelper は「方法」についてより多くを語り、意図についてはあまり語りません。代わりに、名前を DisplayNameFormatter に変更すると、意図がより明確になります。DisplayName は非常に具体的であり、Formatter は結果を表現しています。Formatter は型である場合もあれば、そうでない場合もありますが、意図を表現しているため、それは重要ではありません。

常に例外があります。たとえば、ASP.Net MVC では、コントローラーは「Controller」で終わる必要があります。そうしないとアプリケーションが機能しません。Domain Driven Design（DDD）などのパラダイムを使用する場合、「Services」、「Repository」、「ValueType」、「Model」などの名前は DDD で意味を持ち、責任を表現しています。

たとえば、UserRepository は、ユーザーデータがデータストアから取得され、保存されることを意味します。

比喩を避ける

比喩は文化的であり、他の文化のエンジニアは意図を理解しないかもしれません。

アメリカ合衆国 での一般的な比喩：

• Beating a dead horse
• Chicken or the egg
• Elephant in the room

ニュージーランド での一般的な比喩：

• Spit the dummy
• Knackered
• Hard yakka

動詞を使用する

Steve Yegge は、名詞より動詞を使用することについて (非常に長い) ブログ投稿 を書きました。

彼のポイントは、動詞を使用することです。アプリケーションは名詞で構成されていますが、名詞は何もしません。システムは名詞だけでは役に立たず、代わりにメソッドの名前でアクションを表現してください。

たとえば、UserAuthentication*(名詞)*.AuthenticateUser*(アクション/動詞)* は、ユーザーの認証情報を検証するアクションを表現しています。

説明的である

説明的であってください。詳細が多いほど良いです。名前に責任を表現してください。

自問してください。このクラスまたは関数が得意とする1つのことは何ですか？

名前を見つけるのに困難がある場合、クラスまたは関数は複数の責任を持つ可能性があり、したがって 単一責任の原則 に違反しています。

意図についてコメントに頼らない

コメントはコードに追加のコンテキストを提供する素晴らしい方法ですが、コメントに頼らないでください。クラスとメソッドの名前は、それ自体で成り立つべきです。

Martin Fowler、Kent Beck、John Brant、William Opdyke、Don Roberts による「リファクタリング：既存コードの設計の改善」では：

… コメントはしばしば消臭剤として使用されます。厚くコメントされたコードを見ると、コメントがそこにあるのはコードが悪いからだということに気付くことはしばしば驚くべきことです。

「リファクタリング」の著者からの別の素晴らしい引用：

コメントを書く必要を感じたときは、まずコードをリファクタリングして、コメントが不要になるようにしてください。88ページ

多くの場合、コードがリファクタリングされてメソッドにカプセル化されると、新しいメソッドを活用できる他の場所を見つけることができます。新しいメソッドの使用を予想していなかった場所です。

メソッドを呼び出すときに、コンシューマーはメソッドについて何か特定のことを知る必要があります。その特定性が名前の一部である場合、コンシューマーはソースコードを確認する必要がありません。

コメントを名前に組み込む例を次に示します。

コメント付き：

// without tracking
var user = GetUserByUserId(userId);

コメントをメソッド名に含めるようにリファクタリング：

var userWithOutTracking = GetUserByUserIdWithoutTracking(userId);

他のエンジニアは、ソースコードを読むか、コメントを見つける必要がある前に、このメソッドにトラッキングがないことを知っています。

コメントは、可能な限り意図を表現する他の方法に頼る場合、最後の防衛線です。物理的および論理的構造と名前を使用して意図を伝えます。

曖昧な意味を持つ名前の使用を控える

曖昧な意味を持つ名前を避けてください。曖昧な名前の意味はプロジェクトごとに異なり、新しいエンジニアが意図を理解するのが難しくなります。

一般的な曖昧な名前のリストを次に示します：

• Helper
• Input
• Item
• Logic
• Manager
• Minder
• Moniker
• Nanny
• Overseer
• Processor
• Shepherd
• Supervisor
• Thingy
• Utility
• Widget

ビジネスドメインと同じ言語を使用する

コードではビジネスドメインと同じ用語を使用してください。これにより、エンジニアと主題専門家（SME）は同じ語彙を共有しているため、アイデアを簡単に通信できます。共有語彙がない場合、翻訳が発生し、必然的に誤解につながります。

私が取り組んだあるプロジェクトでは、ビジネスは「Pupil」で始まり、その後「Student」に切り替わりました。ソフトウェアエンジニアは、用語の変更を反映するようにソフトウェアを更新することはありませんでした。新しいエンジニアがプロジェクトに参加したとき、ほとんどの人は Pupil と Student が異なる概念だと信じていました。

業界用語を使用する

可能な限り、ソフトウェア業界全体で意味を持つ用語を使用してください。

ほとんどのソフトウェアエンジニアは、「factory」という名前のものを見ると、すぐにファクトリーパターンを思い浮かべます。

「Clean Architecture」や「Domain Driven Design」などの既存のアプリケーションパラダイムを使用すると、アイデア共有が促進され、エンジニアが互いにアイデアを通信するための共通言語が作成されます。

最悪の命名は、業界全体の用語を採用し、それに異なる意味を与えることです。

ブール値に名前を付けるとき…

ブール値の名前は、常に true または false のいずれかの値を持つ質問への答えである必要があります。

たとえば、isUserAutheticated は、答えが yes (true) または no (false) のいずれかです。

次のような単語を使用してください：

• Has
• Does
• Is
• Can

否定された名前を避けてください。例えば：

否定された変数名：

var IsNotDeleted = true; // this is confusing

if(!IsNotDeleted) { // it gets even more confusing when the value is negated
  //Do magic
}

否定されていない変数名：

var IsDeleted = true; // this is confusing

if(!IsDeleted) { 
  //Do magic
}

結論として

表現力のある名前を選択することは、意図、設計、およびドメイン知識を次のエンジニアに伝えるために重要です。多くの場合、欠陥を修正したり、新しい機能を組み込むためにコードに取り組んでいます。そして、私たちは継続的にコードをコンパイルして、それがどのように機能するかを理解しようとしています。命名は、前のエンジニアが何を考えていたかについてのヒントを与えてくれます。過去と未来のエンジニア間のこのコミュニケーションがなければ、アプリケーションの成長に自分たちを妨げます。潜在的にプロジェクトを失敗に運命づけます。