意味のある簡潔なメソッド命名ガイドライン

最近私はオープンソースプロジェクトのリリースを開始しましたが、私はライブラリの唯一のユーザーでしたが、名前は気にしませんでしたが、学習しやすくするために各メソッドに巧妙な名前を割り当てたいことを知っていますが、簡潔な名前を付けて、簡単に記述できるようにします。

命名に関するいくつかのガイドラインについて考えていましたが、文字の大文字小文字やいくつかの簡単なメモだけに注意を払う多くのガイドラインを知っています。ここでは、意味のある、しかし簡潔な命名のガイドラインを探しています。

たとえば、これは私が検討しているガイドラインの一部です。

• 既存のアイテムをターゲットに追加する場合は「追加」を使用し、新しいアイテムを作成してターゲットに追加する場合は「作成」を使用します。
• 既存のアイテムをターゲットから削除する場合は[削除]を使用し、アイテムを完全に削除する場合は[削除]を使用します。
• AddXXXメソッドをRemoveXXXメソッドとペアリングし、CreateXXXメソッドをDeleteXXXメソッドとペアリングしますが、これらを混在させないでください。

上記のサンプルが示すように、英語の文法と単語の意味に準拠する命名方法やその他のアイテムを支援するオンライン資料を見つけたいと思います。

上記のガイダンスは、英語を母国語とする人にとって直感的かもしれませんが、私にとっては英語が私の第二言語であると私はこのようなことについて話す必要があります。

ネーミング。ソフトウェア開発に関する最も難しいことの1つ:)

私が何かに名前を付けるとき、優先順位のセットはここにあります：

• 私の言語のイディオムに従ってください。Rubyはアンダースコアが好きです。Javascriptはキャメルケースが好きです。あなたがどんな言語にいても従うべき慣習です。
• APIの意図を明らかにします。「send_http_data」ではなく、「post_twitter_status」です
• 実装の詳細を漏らさないようにします。たとえば、変数の前に型を付けます。
• 前のガイドラインに違反することなく、必要以上の文字を使用しないでください。

明らかにこれはかなり単純なアプローチです。命名は微妙です。

さらなる研究については、The Art of Readable Codeを読むことをお勧めします。メソッドの命名に関する優れた簡潔なアドバイスを提供するからです。さらに多くの研究のために、ボブ・マーティンのクリーン・コードを強く勧めることはできません

命名のスタイルや規約を体系化する誘惑は、場合によっては、たとえばハンガリー語表記を使用するなど、現在では不十分な習慣と見なされている習慣につながる可能性があります。簡単な答えは、あたかもそれが個別に決定されるいくつかの別個のものであるかのように命名規則とスタイルを忘れて、代わりにそれが実際に表すものに基づいてシステム内のすべてに名前を付けることに集中することです。各メソッドの機能を概念的に1つのことだけを行うように制限し、メソッド名が実際にメソッドが行うべき1つのことを記述している場合、メソッド名は自然に簡潔になる傾向があります。

変数、フィールド、クラス、およびファイル名は別のものです。変数名が長くなりすぎている場合は、これらの項目を非常に詳細に説明するか、より小さな部分に分割するか、より抽象的なもので説明する必要がある複雑なものを表現することをお勧めしますマナー。

結局のところ、名前が行全体を占めるようなwithいコードや、その値を奪うほどglibなコードは避けたいと思います。

私にとって、何かの良い名前を見つけることは、常にその存在を正当化する必要があるオブジェクトと考えることに戻ります。自問してみてください：

• クラス/メソッド/変数は何をしますか、すなわち、そのより広い目的は何で、何のためですか？
• その目的について具体的に何を伝える必要がありますか。つまり、名前がその中に持つ必要がある重要な部分は何ですか？

ほとんどの開発者は、ネーミングに関しては可読性が常に最重要であることを認めるでしょう。コードを書いている間に意味を理解するためだけにコードを書くのではなく、将来のある時点で初めてコードを見る人があまり考えずにあなたの意図を理解できるようにそれを書いてください。コードは1回だけ記述しますが、その存続期間中に何度も編集し、さらに読む必要があります。

コードは自己文書化する必要があります、つまり、あなたの命名は何かが何をするかを明らかにするべきです。コメントでコードの行が何をするかを説明する必要があり、名前を変更しても十分に改善されない場合は、適切な説明的な名前で新しい行にリファクタリングすることを真剣に検討する必要があります。新しいメソッド呼び出しは、何が起こっているかを説明します。長い名前を持つことを恐れないでください。もちろん、クラス/メソッド/変数名で小説を書くべきではありませんが、短すぎるよりも長すぎて説明的な名前を持ちたいので、フードの下を見て、それが何をするのかを理解する必要があります。x / y座標や一般的に使用される頭字語などの明らかな例外を除き、単一文字の名前と略語は避けてください。「backButton」の代わりに「bkBtn」を呼び出す

あなたの言語が許す限り、コードを英語の文章のように読んでください。オブジェクトは名詞を使用し、メソッドは動詞を使用します。通常、ブールメソッドは「is」で始まりますが、「can」、「should」、「does」など、ユースケースに応じて意味をさらに伝える多くのオプションがあります。もちろん、すべての言語がSmalltalkほど優れているわけではありませんが、一部の記号は一般的に文の一部であると理解されています。個人的に可能な限り他の言語に取り入れたい2つのSmalltalk規約は、ループパラメーターの名前の前に「each」を、メソッドパラメーターの前に記事「a」（またはコレクションの「an」または「some」）を付けることです。 。これはJavaの一般的な標準ではない可能性があり、誰でもこのビットを無視してかまいませんが、しかし、これによりコードの可読性が大幅に向上することがわかります。たとえば（Javaの例）：

public boolean shouldConsiderAbbreviating(List<String> someNames) {
  for (String eachName : someNames) {
    if (isTooLong(eachName)) {
      return true;
    }
  }
  return false;
}

これは、Javaの知識が少しでもある人には、次のように読めるはずです。

いくつかの名前（文字列）のリストを短縮することを検討する必要があるかどうかを判断するには、いくつかの名前を反復処理し、名前ごとに長すぎるかどうかを判断します。もしそうなら、リターンtrue; 長すぎるものがない場合は、を返しfalseます。

特により複雑なメソッドでは、引数stringsとループ変数の名前だけで上記のコードと比較してくださいstring。名前を一目見ただけで使用法が明らかになるのではなく、違いを注意深く見る必要があります。

適切なネーミングを見つけることは、常により多くの要素間の妥協です。あなたは完全に満足することは決してありません。

そうは言っても、あなたの母国語がそうでないとしても、英語はプログラミング言語トークンが形成される言語であると考えてください。英語のような構文を使用すると、キーワードが見つかるたびに「壊れた読み取り規則」がないため、コード読み取りがより「流fluent」になります。

一般に、などobject.method(parameters)のスキームに一致するものを検討してくださいsubject.verb(complements)。

ジェネリックプログラミングをサポートする必要がある場合のキーポイントは、一貫性のある「動詞」のセット（特に、ジェネリックアルゴリズムで使用する必要があるもの）を選択することです。

名詞については、クラスにはare（概念的に）名前を付け、オブジェクトには名前を付けますare for。

それは間、言ったlist.add(component)とcomponent.add_to(list)最初のを好みます。一般に、「能動的推移的」動詞は、受動的または再帰的な対応物に対する行動をよりよく表しています。設計があなたを圧迫しない限り。

メソッド名の長さについて心配する必要はありません。メソッド名が実行していることを明確に反映していることを確認してください。これは他の何よりも重要です。メソッド名が長すぎると感じる場合は、シソーラスを使用して、同じことを意味する短い単語を見つけます。たとえば、のFind代わりに使用しますRetrieve。

同様に重要なのは、クラスに選択する名前です。これらは、メソッド名を見るときに多くのコンテキストを提供します。次のようなメソッドシグネチャ：

public User Find(int userId);

以下よりも理解しやすいです：

public Person Find(int personId);

クラス名から取得したコンテキストは、特定のタイプの人、つまりシステムのユーザーを見つけるためUserのプログラマーに伝えるFind()ためです。Personクラスを使用するバージョンでは、そもそもメソッドを使用する必要がある理由についてのコンテキストは提供されません。

プラットフォーム上の他の人がそれをどのように行うかを見てください-一部のより大きなプレーヤーは、コードスタイルと命名ガイドラインさえ持っているかもしれません。

一部のプラットフォームは短い名前を好みます（たとえば、Win32 C API _tcsstrでは文字列内の文字列を検索する関数です-それは明らかではありませんか？） 、文字列内の部分文字列を別の文字列に置き換えて、コピーとして結果を返すメソッドが呼び出されますstringByReplacingOccurrencesOfString: withString:）。後者は非常に理解しやすく、書くのがやや難しいだけです（特にコード補完の場合）。

コードを書くよりも頻繁にコードを読み（オープンソースライブラリの場合も同様）、読み取りは書き込みよりも難しいので、読み取り用に最適化します。簡潔さのために最適化するのは最後だけであり、明快さを薄めることなく、できるだけ多くを奪います。

1. このコードで作業するすべての開発者が同じ英語以外の言語を話さない限り、英語を想定してください。

2. 一般的に受け入れられている命名規則とスタイルを研究します。 あなたの指導原則は明確でなければなりません。スタイルはプログラミング言語によって異なります。

3. コード内のさまざまなオブジェクト間の関係を理解し​​やすくするために、名前付けでできることは何もありません。そのためには、よく書かれたコメントとドキュメントが必要です。

1. プレフィックスを使用します。一連のメソッドを使用して同様のことを行うか、何らかの方法でグループ化できる場合は、名前の前に共通のプレフィックスを付けて、これらのメソッドの共通点を示します。
2. 他の人に名前をすぐに理解してもらいたい場合は、不明瞭な略語を使用しないでください（API命名で重要）