كيف يمكن أن يكون "التوثيق الذاتي" رمزيًا دون أن يكون مزعجًا؟[مغلق]

Question

لست متأكدًا من أفضل الممارسات الموجودة هنا، ولكن غالبًا ما أرى أسماء متغيرات مختصرة خاصة عندما يكون النطاق صغيرًا.لذا (لاستخدام أمثلة روبي البسيطة) بدلاً من def add_location(name, coordinates), ، أرى أشياء مثل def add_loc(name, coord)- وربما أرى شيئًا كهذا def add_loc(n, x, y). أتصور أن الأسماء الطويلة قد تتعب الشخص عندما يعتاد على رؤية الاختصارات.

هل يساعد الإسهاب في سهولة القراءة، أم أنه يؤذي أعين الجميع؟ هل يفضل الناس الاختصارات والأسماء المختصرة على الأسماء الطويلة؟

Answer 1

أنا شخصياً أفضل رؤية الأسماء الطويلة التي تعني في الواقع شيئًا ما دون الحاجة إلى تحديد السياق أولاً.بالطبع، المتغيرات التي لا تعطي معنى حقيقيًا، مثل العدادات، ما زلت أستخدم أسماء متغيرات صغيرة لا معنى لها (مثل i أو x)، ولكن غير ذلك الإسهاب هو الوضوح معظم الوقت.وهذا ينطبق بشكل خاص على واجهات برمجة التطبيقات العامة.

ومع ذلك، يمكن أن يؤخذ هذا بعيدًا جدًا.لقد رأيت بعض أكواد VB في الماضي بهذه الطريقة السخيفة.الاعتدال مثل كل شيء آخر!

Answer 2

وأنا في الواقع استخدام أسماء المتغيرات طويلة في كل وقت، بعد كل بيئات التطوير الحديثة وtexteditors لها الانتهاء، لذلك فلا بأس باستخدام index بدلا من ذلك إذا ط. والاستثناء الوحيد لدي هو عند التعامل مع الإحداثيات ب / ج x وy جعل معظم معانيها هناك.

Answer 3

وأبدا ابر.

Answer 4

وينبغي إيلاء متغير أقصر اسم الممكن أن ينقل نحو كاف الغرض منه.

والإفراط في الإسهاب يميل إلى إخفاء لغوي، وبناء الجملة المهم.

وعبر برنامج كله (أو التطبيق / النظام) يجب أن تكون تسمية المتغيرات مع نمط ثابت ويجب أن تكون تسمية أشياء مماثلة على نحو مماثل. في حالة وجود اتفاقية داخل المجتمع اللغة، فإنه ينبغي مراعاتها (حتى لا camelCaseRubyVariableNames) ما لم يكن هناك سبب مقنع لعدم القيام بذلك.

والاختصارات، إذا ما استخدمت، ينبغي أن تطبق باستمرار في كل مكان وإذا كان المجال محددة، يجب أن تسجل في مكان ما. إذا كان شخص ما سوف تنفق أي مبلغ من المفيد من الوقت مع رمز ثم أنها سوف تتعلم قريبا.

إذا كنت بحاجة إلى الجمع بين ما لا يقل عن خمس أو ست كلمات لتسمية متغير ثم أود أن اقترح هل يمكن أن تبحث في <لأ href = "http://c2.com/cgi/wiki؟CodeSmell" يختلط = "noreferrer"> كود رائحة و الروتين كنت تعمل يمكن أن تستفيد من القليل من العمل.

وفي الغالب، رغم ذلك، إذا كنت على بينة من المزالق وفعلا <م> التفكير حول ما كنت تكتب، وهناك احتمالات أن التعليمات البرمجية ستكون معقولة. تخيل نفسك واصفا وظيفة كنت تعمل على لزميل جديد - أقل كنت تعتقد أنك سوف تحتاج إلى القول إن أفضل رمز ربما هو

Answer 5

حاول قراءة الكود الخاص بك بعد عام واحد.سترى قيمة أسماء المتغيرات ذاتية التوثيق، وقيمة تعليقات التعليمات البرمجية (وخاصة قيمة التعليمات البرمجية النظيفة)

عندما تحصل على كود مصدر شخص آخر ولا تفهمه، فمن السهل أن تفكر "حسنًا، إنه ليس مبرمجًا جيدًا مثلي" ولكن عندما تدرك أن الكود الخاص بك يصعب قراءته، فإليك ما يلي:"ماذا كنت أفكر؟"

على المدى الطويل، يساعد الإسهاب في قابلية الصيانة.بالنسبة للنص القصير المكون من سطر واحد، لا يزال بإمكانك استخدام "setLocNm" بدلاً من setLocationName"

يمكن لأي أحمق أن يكتب تعليمات برمجية يمكن للكمبيوتر أن يفهمها.المبرمجون الجيدون يكتبون كودًا يمكن للبشر فهمه. -مارتن فاولر

Answer 6

شخصيًا، أجد الإسهاب أمرًا جيدًا، لكن من السهل الإفراط في الإسهاب أيضًا، وهو أمر سيء.هناك توازن، ويمكن أن تدخل الاختصارات في هذا التوازن أيضًا.

هذه هي قواعدي العامة:

• يمكن أن تكون التكرارات حرفًا واحدًا، على سبيل المثال. i, j, k, ، إلخ.
• متغيرات أخرى مكونة من كلمة واحدة مثل التبديلات المنطقية، وما لم يتم اختصاره أبدًا، على سبيل المثال. installing, done, ، إلخ.
• تعد متغيرات الكلمات وأسماء الوظائف المتعددة مرشحة للاختصار، ولكن فقط إذا بدأت تصبح طويلة بشكل سخيف (على سبيل المثال، 20-25+ حرفًا).الاختصار الذكي هو المفتاح هنا. function => func على سبيل المثال، ولكن أبدا fun, f, ، أو functi

Answer 7

وأنا تصفحها من خلال الإجابات، ولكن أنا لا نرى ما اذا كان يتم تغطية التالية. هنا غني ...

وإذا كنت اختصار أو أن تكون مطول، فقط تأكد من أن كنت قد استخدمت أي كلمات أكثر من اللازم والمعنى هو لعنة وضوحا.

ولكن حتى بعد هذه التصفية إذا معرفات تبدو مطول، لديك عيب في التصميم الخاص بك.

def initialize_report_template()
end

وكان ينبغي أن يكون ...

class ReportTemplate
    def initialize()
    end
end

Answer 8

وأسماء أطول هي أفضل بكثير. أذكر لكم أن كنت كثيرا ما نرى الأسماء المختصرة في نطاقات صغيرة. من الذي يقول ان نطاق صغير يبقى كما ينمو البرنامج؟

وبطبيعة الحال، XCoordinateForCurrentLocationOfSelf هو اسم مثير للسخرية، حتى مجرد أن تكون معقولة. خاصة إذا كنت المشي في مشروع كنت قد لا يعمل على قبل، سيكون لكم شكرا لكل من يستخدم وظيفة وصفية وأسماء المتغيرات.

Answer 9

وأعتقد أن كل شيء على مايرام لاختصار عندما يكون اسم سيضر القراءة أو مجرد أن تكون زائدة عن الحاجة.

مثال 1: حجة لطريقة حيث نوع ينقل allready قد كل المعلومات اللازمة

مثال 2: المتغير الذي سيتم استخدام الكثير بطريقة واضحة

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

مثال 3: abbrevations الاصطلاحية. ط، ي، وقد ذكر ك allready قد. "بينالي الشارقة" أعلاه هو واحد في الكود، وربما كل فريق لديه أكثر زوجين.

Answer 10

والهدف للأقصر بدلا من أطول، ولكن القارئ فهم ينبغي رابحة <لأ href = "http://steve-yegge.blogspot.com/2008/09/programmings-dirtiest-little-secret.html" يختلط = "نوفولو noreferrer "> الكسل لكتابة كل مرة واحدة.

وكما قال آخرون، طول اسم المتغير يجب أن المنطق ليس غامضا أو الخوارزمية. على سبيل المثال، في الحساب، ونحن نكتب

( 1 + 5 ) * 3 = 18

وليس

three multiplied by the sum of one and five equals eighteen

ولأننا نحاول لفت الانتباه إلى أمور أخرى من وضوح العناصر المتورطة في التعبير.

وأنا أميل للحفاظ على المتغيرات 1-3 الكلمات، تختزل فقط عندما تتجاوز 24 حرفا أو نحو ذلك. وأقل كثيرا ما يستخدم متغير، والأرجح أنا للا تتردد في جعل اسم المتغير طويلة. أكثر استخداما المتغيرات سأدلي أقصر.

Answer 11

وماكس كانات الكسندر، كبير مهندسي بجزيلا، يقول هذا على بلوق له:

<اقتباس فقرة>   

والقانون ذاته يجب أن تأخذ مساحة في نسبة إلى كم يعني لديه.

     

وأساسا والرموز الصغيرة التي تعني   الكثير جعل كود الصعب قراءة. طويل جدا   الأسماء التي لا تعني الكثير أيضا جعل   رمز القرص الثابت للقراءة. كمية   وهذا يعني والمساحة تناولها يجب   أن ترتبط ارتباطا وثيقا بعضها البعض.

http://www.codesimplicity.com/post/readability-and -naming-الأشياء /

وانها وظيفة الثاقبة للغاية حول تسمية الأشياء. وأحث الجميع على قراءتها!

Answer 12

والمرة الوحيدة التي أنا أقبل الاختصارات هو للمتغيرات المحلية التي ليست سوى في نطاق فترة صغيرة من الزمن.

وهذا يعني أنها يجب أن تكون قادمة في نطاق مع طريقة جدا للقراءة أو منشئ.

Answer 13

وأنا أتفق مع Kilhoffer. أنا أفضل أن أرى أسماء المتغيرات وصفية في سياق تقريبا. سأختصر إذا كان لي أسماء المتغيرات هي أطول من 20 حرفا أو نحو ذلك، وعادة مع الكلمات في اسم المتغير (على سبيل المثال: "SomeVeryLongVarValue").

وبطبيعة الحال، أنا أيضا استخدام التدوين الهنغارية كلما استطعت، ولذا فإنني قد يكون جيدا في معسكر الطرف الآخر في محاولة لجعل المتغيرات أسماء بلدي صفية أكثر من اللازم، حسب وجهة نظرك.

Answer 14

وأنا ربما ستكون استهجن تماما ولكني أردت التأكد من سمع هذا الرأي.

وعلى الرغم أسماء المتغيرات أطول يمكن أن يكون أكثر وصفي يمكنهم البدء في الوحل القصد الأصلي من البرنامج. أشعر أن على عناصر API من المهم أن لها أسماء واضحة وذات مغزى في السياق الذي سيتم استخدامها.

وداخل كل وظيفة أو طريقة هذا غالبا ما يكون قصة مختلفة. أحاول أن أكتب أقل والحفاظ عليه مقتضب جدا. وهذا ما يعرف البرمجة اسبارطي الله على السيد أتوود و هذا سبيل المثال أنيق. نعم، وزورت المثال بوضوح ولكنه شرح كيفية وجود حفل أقل القليل يمكن أن تجعل في الواقع قراءة البرنامج أسهل.

وحظا سعيدا.

Answer 15

عند البرمجة كنت تستخدم بناء الجملة بحيث يمكن للانسان ان يقرأها، وطول أسماء المتغيرات والأساليب، الخ ... هي irrevelant حقا.

وكلما كان ذلك أفضل مطول عادة، مع بيئة تطور جيد يجب أن يكون إنجاز قانون على أي حال، لذلك يمكنك ببساطة ضرب "add_L" + TAB لإنهاء استدعاء الأسلوب.

Answer 16

وأعتقد أن المشكلة الرئيسية مع الاختصارات هي أن على ليس كل الناس يختصر على نفس الطريق ، أو حتى عند العمل مع كثير من الناس فقط يمكن أن تزيد من احتمال الخطأ عندما الترميز. على سبيل المثال إذا كان لديك ثابت يمكن أن يطلق عليها SOMETHING_INTERFACE، ربما بعض المطورين سوف اختصر أنها SOMETHING_INTFACE، والبعض الآخر كما SOMETHING_IFACE أو SOMETHING_IF، SMTHING_IFACE ...

ومع كلمتين فقط هل يمكن أن يكون ما لا يقل عن نصف دزينة من أكثر أو أقل "المنطق" الاختصارات الممكنة، لذلك أعتقد أنه من الأفضل في معظم الحالات إلى الكتابة دون الاختصارات ومع المزيد من الأسباب إذا كنت تريد أن يكون النفس كود -docummented.

وأسماء طويلة جدا يمكن أن تكون مزعجة في بعض الأحيان، ولكن يمكن أيضا أن تختصر في نطاقات محلية جدا باستخدام المتغيرات auxiliar.

Answer 17

ومعظم الناس البصر قراءة، ويأخذ لم يعد لقراءة كلمة ثم لقراءة حرف مفرد. لذلك دائما استخدام أسماء ذات مغزى. هل لديهم أن تكون كاملة الأوصاف 7 كلمة، لا ولكنها تحتاج إلى أن تكون أطول بما فيه الكفاية لفهم.

وأنا يمكن أن تقبل add_loc (الاسم، COORD)، لأنها طويلة بما فيه الكفاية استطيع ان اقول ما هي عليه. في add_loc (ن، س، ص)، وأود أن يعترض على 'ن' بدلا من اسم. يمكن أن أعيش مع X و Y وهذه هي الأسماء المقبولة للالإحداثيات.

لأنظمة شخص غير مطلع على تنسيق كنت أرى فيها (، وينسق الاسم) add_location سيكون أكثر وضوحا.

وعندما تكون في شك، استخدام أسماء أطول.

Answer 18

"كل شيء على مايرام لمعرفة أسرار القتل، ولكن يجب أن لا حاجة لمعرفة كود يجب أن تكون قادرا على قراءتها." - ستيف C. ماكونيل

ومع ذلك، إذا كنت تعتقد أنك أو أي شخص آخر يحتاج أسماء المتغيرات صريحة أكثر من اللازم وهلم جرا، لا تتردد في تقصير منهم.

Answer 19

وأقترح اتخاذ نهج الحد الأدنى. استخدام أقل قدر ممكن مع ضمان التعليمات البرمجية يبقى واضحة وموجزة وإلى هذه النقطة.

Answer 20

وينبغي أن يكون أسماء وصفية طويلة خارج نطاق الأشياء مثل الثوابت وغلوبالس. أحيانا اسم طويل حقا سيجعل من "رائحة" ما يكفي للإشارة إلى أنها جود بأنها غير مرغوب فيه. هذا أمر جيد احتوائه وسوف 1 - جعل الناس تجنب ذلك، 2 - زيادة pressue إلى ريفاكتور رمز لجعله يذهب بعيدا