どのように＆＃8220;自己文書化＆＃8221;迷惑にならずにコードを作成できますか？ [閉まっている]

StackOverflow https://stackoverflow.com/questions/214160

  •  03-07-2019
  •  | 
  •  

質問

ベストプラクティスがここにあるかどうかはわかりませんが、特にスコープが小さい場合は、変数名が省略されていることがよくあります。だから（単純なRubyの例を使用するため） def add_location（name、axes）の代わりに、 def add_loc（name、coord）＆＃8212;のようなものが見えます。 def add_loc（n、x、y）のようなものも表示されます。長い名前は、略語を見ることに慣れている人を疲れさせるかもしれないと思います。

冗長性は読みやすさの向上に役立ちますか、それとも全員の目を痛めますか？

役に立ちましたか？

解決

個人的には、コンテキストを最初に決定する必要なく、実際には何かを意味する長い名前を見るでしょう。もちろん、カウンターなどの本当の意味を貸さない変数は、小さな意味のない変数名（ i や x など）を使用しますが、それ以外の場合は冗長性は明快です。これは、パブリックAPIで特に当てはまります。

ただし、これは行き過ぎです。私は過去にそのような方法でいくつかのVBコードを見てきました。他のすべてと同じようにモデレート！

他のヒント

すべての最新のIDEおよびテキストエディターが完了した後、実際には常に長い変数名を使用するため、iの代わりに index を使用しても問題はありません。私が持っている唯一の例外は、座標b / c x および y が最も意味をなす場合です。

絶対にしないでください。

変数には、その目的を適切に伝える最短の名前を付ける必要があります。

過度の冗長性は構文を隠す傾向があり、構文が重要です。

プログラム（またはアプリケーション/システム）全体で、変数には一貫したスタイルの名前を付け、同様のものには同様の名前を付ける必要があります。言語コミュニティ内に慣習が存在する場合、そうしない特別な理由がない限り、それを遵守する必要があります（したがってcamelCaseRubyVariableNamesは使用しないでください）。

略語を使用する場合は、どこにでも一貫して適用し、ドメイン固有の場合はどこかに記録する必要があります。誰かがコードで有用な時間を費やそうとするなら、すぐに学習します。

変数に名前を付けるために5つまたは6つの単語を組み合わせる必要がある場合は、コードの匂いと作業中のルーチンには、少しの作業が役立つ場合があります。

しかし、ほとんどの場合、落とし穴に気づいていて、実際に自分が書いているものについて考える場合、コードが妥当である可能性があります。新しい同僚に取り組んでいる機能を自分で説明することを想像してください。あなたが言う必要があると思うほど、コードはおそらく良いでしょう。

1年後に独自のコードを読んでみてください。自己文書化変数名の値と、コードコメントの値（および特にクリーンコードの値）の両方が表示されます

誰か他の人のソースコードを入手し、それを理解していないとき、「まあ、彼は私ほど優れたプログラマーではない」と考えるのは簡単です。しかし、自分のコードを読むのが難しいことに気付いたとき、次のようになります：＆quot;私はどう思いましたか？＆quot;

長期的には、冗長性は保守性に役立ちます。短い1行のスクリプトの場合、「setLocNm」を引き続き使用できます。 setLocationName＆quot;の代わりに

誰でも、コンピューターが理解できるコードを書くことができます。優れたプログラマーは、人間が理解できるコードを作成します。 -Martin Fowler

個人的に、冗長性は良いことですが、過度に冗長になるのは簡単です。これは悪いことです。バランスがあり、略語もそのバランスに含まれます。

これらは私の一般的なルールです：

  • イテレータは1文字にすることができます。 i 、 j 、 k など
  • ブール値のトグルなど、他の1ワードの変数。 installing 、 done など
  • 複数の単語変数と関数名は略語の候補ですが、それらが途方もなく長くなり始めている場合（20〜25文字以上）に限られます。ここでは、インテリジェントな略語が重要です。 function =＆gt;たとえばfunc ですが、 fun 、 f 、または functi
    • は使用できません

回答を閲覧しましたが、次の項目がカバーされているかどうかわかりません。ここで...

略語であろうと冗長であろうと、必要以上の単語を使用していないこと、そしてその意味が明らかであることを確認してください。

ただし、このフィルタリングの後でも、識別子が冗長に見える場合は、設計に欠陥があります。

def initialize_report_template()
end

すべきだった... 

class ReportTemplate
    def initialize()
    end
end

長い名前の方がはるかに優れています。あなたは、あなたがしばしば小さなスコープで省略名を見ると言います。ソフトウェアが成長してもスコープは小さいままであると言うのは誰ですか？

もちろん、XCoordinateForCurrentLocationOfSelfはとんでもない名前ですので、合理的な名前にしてください。特に、以前に取り組んだことのないプロジェクトに足を踏み入れている場合は、説明的な関数名と変数名を使用してくれた人に感謝します。

名前が読みやすさを損なう場合や、単に冗長になる場合は省略しても構いません。

例1：型がすでに必要なすべての情報を伝えるメソッドの引数。

例2：明らかに多くの方法で使用される変数

StringBuilder sb = ...
sb.append(...
sb.append(...
return sb.toString();

例3：慣用的な略語。 i、j、kについてはすでに言及しました。 ＆quot; sb＆quot;上記のコードはコード内の1つであり、各チームにはおそらくさらに2つあります。

長くするのではなく短くすることを目指しますが、読者の理解は毎回入力するのが面倒。毎回。

他の人が言ったように、変数名の長さはロジックやアルゴリズムを曖昧にするべきではありません。たとえば、算術では、次のように記述します

( 1 + 5 ) * 3 = 18

ではなく

three multiplied by the sum of one and five equals eighteen

表現に含まれる要素の明瞭さ以外のことに注意を向けようとしているため。

変数は1〜3ワードに保持する傾向があり、24文字程度を超える場合にのみ短縮します。変数の使用頻度が低いほど、変数名を自由に長くすることができます。より頻繁に使用される変数は短くします。

BugzillaのチーフアーキテクトであるMax Kanat-Alexanderは、ブログで次のように述べています。

  

コード自体は、その意味の大きさに比例してスペースを占有する必要があります。

     

基本的に、   多くの場合、コードが読みにくくなります。とても長い   あまり意味のない名前も   読みにくいコード。の量   意味と占有されるスペースは   互いに密接に関係している。

http://www.codesimplicity.com/post/readability-and -naming-things /

これは、ものの命名に関する非常に洞察に満ちた投稿です。みんなに読んでもらいたい！

略語を受け入れるのは、短時間だけスコープ内にあるローカル変数の場合のみです。

これらは、非常に読みやすいメソッドまたはコンストラクターでスコープに入る必要があることを意味します。

キルホッファーに同意します。ほぼすべてのコンテキストで説明的な変数名を表示することを好みます。通常、変数名に単語が含まれている場合、変数名が20文字以上の場合は省略します（例：＆quot; SomeVeryLongVarValue＆quot;）。

もちろん、できる限りハンガリー記法も使用するので、あなたの視点に応じて、変数名を過度に説明的にしようとする他の極端なキャンプにいるかもしれません。

おそらく完全にブーイングされるでしょうが、この意見が聞かれることを確認したかったです。

変数名を長くすると、よりわかりやすくなりますが、プログラムの本来の意図を模倣し始める可能性があります。 API要素では、使用されるコンテキストで明確で意味のある名前を付けることが重要だと思います。

各関数またはメソッド内では、これはしばしば異なるストーリーです。私は書く量を減らして、とても簡潔にしようとしています。これは、 Mr. Atwood およびこれ気の利いた例。はい、この例は明らかに装備されていますが、儀式を少し行うことで実際にプログラムを読みやすくできることを示しています。

がんばって。

プログラミングの際には、人間が読めるように構文を使用していますが、変数名、メソッドなどの長さは本当に重要です。

通常は、冗長性が高いほど、開発環境が良好であれば、とにかくコード補完を行う必要があるため、「add_L」+ TABを押してメソッド呼び出しを終了するだけです。

略語の主な問題は、すべての人が同じように略すわけではないということだと思います。したがって、多くの人と作業する場合、コーディング時のエラーの確率が高くなるだけです。たとえば、SOMETHING_INTERFACEと呼ばれる定数がある場合、一部の開発者はそれをSOMETHING_INTFACEと略し、他の開発者はSOMETHING_IFACEまたはSOMETHING_IF、SMTHING_IFACEと略します...

2語のみで、少なくとも半ダース以上の「ロジック」を使用できます。可能性のある略語なので、ほとんどの場合、略語なしで、自己文書化されたコードが必要な場合は、より多くの理由で書く方が良いと思います。

非常に長い名前はときどき迷惑になりますが、非常にローカルなスコープでは補助変数を使用して短縮することもできます。

ほとんどの人は視覚を読んでいます。単語を読むのに、個々の手紙を読むのに時間がかかりません。したがって、常に意味のある名前を使用してください。 7語の完全な説明である必要がありますか？いいえ、理解するのに十分な長さが必要です。

add_loc（name、coord）を受け入れることができます。それらが十分に長いので、それらが何であるかを知ることができます。 add_loc（n、x、y）では、名前ではなく「n」に反対します。これらは座標の受け入れられた名前であるため、XとYで生きることができます。

座標系に精通していない人にとっては、add_location（name、axes）がより意味のある場所を見つけることができました。

疑わしい場合は、より長い名前を使用します。

＆quot;殺人ミステリーを理解することはできますが、コードを理解する必要はありません。読むことができるはずです。＆quot; -Steve C. McConnell

とはいえ、あなたや他の誰かが過度に明示的な変数名などを必要としていると思ったら、気軽に短縮してください。

最小限のアプローチを取ることをお勧めします。コードを明確で簡潔かつ要領を保ったまま、できるだけ少し使用します。

定数やグローバルなどのスコープ外のものには、説明的な名前を付ける必要があります。時々、本当に長い名前は「臭い」になります。存在が望ましくないことを示すのに十分です。これは、1-人々にそれを避けさせ、2-圧力を上げてコードをリファクタリングして消滅させるため、良いことです。

ライセンス： CC-BY-SA と 帰属
所属していません StackOverflow
scroll top