كيف تحب التعليقات ؟ [مغلقة]

Question

ما هي أفضل الممارسات التعليقات ؟ عندما ينبغي أن يكون استخدامها ، وما ينبغي أن تحتوي ؟ أو هي تعليقات حتى حاجة ؟

Answer 1

تعليقات ضرورية من أجل الصيانة.النقطة الأكثر أهمية هو أن نتذكر أن أشرح لماذا كنت تفعل شيئا لا ما كنت تفعل.

Answer 2

في المدرسة كانت القاعدة أن أعلق كل شيء, لدرجة أن التعليقات تفوق رمز.أعتقد أن هذا سخيف.

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

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

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

Answer 3

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

Answer 4

كما في كثير من الأحيان الجواب هو:ذلك يعتمد.أعتقد أن السبب كتبت تعليق مهم جدا لهذا القرار إذا كان التعليق هو جيدة أو سيئة.هناك عدة أسباب محتملة التعليقات:

• لجعل هيكل أوضح (أيوالتي انتهت حلقة هنا)

السيئة: هذا يشبه ممكن كود رائحة.لماذا هو رمز معقدة جدا, أنه يحتاج إلى تعليق واضح هذا ؟

• لشرح ما لا

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

• للإشارة إلى الحل/أ خلل

جيد: في بعض الأحيان حل مشكلة يبدو واضحا ، ولكن مقاربة بسيطة لديه مشكلة.إذا كان يمكنك إصلاح هذه المشكلة ، قد يكون من المفيد إضافة تعليق لماذا هذا النهج الذي تم اختياره.وإلا آخر مبرمج في وقت لاحق يمكن أن أعتقد ، أنه 'الأمثل' رمز إعادة علة.التفكير دبيان بينسل المشكلة.Debian-المطورين على إزالة unitialized متغير.عادة ما unitialized متغير مشكلة في هذه الحالة كان هناك حاجة العشوائية.رمز التعليق قد ساعد على توضيح ذلك.

• الوثائق-الأغراض

جيد: بعض الوثائق التي يمكن أن تتولد من تنسيق التعليقات (أيجافادوك).فإنه من المفيد أن الوثيقة واجهات برمجة التطبيقات العامة ، وهذا هو يجب أن يكون.المهم هو أن نتذكر أن الوثائق تحتوي على نية رمز, لا تنفيذ.لذلك يجيب على التعليق والسؤال لماذا كنت في حاجة إلى طريقة (وكيف يمكنك استخدامه) أو ما الطريقة ؟

Answer 5

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

ما هي النسبة المئوية من الشعوب الأخرى رمز هل تقرأ ما أفهم..ربما قرأت الكثير من الكلاسيكية asp, Perl و C++ ولكن معظم الاشياء قرأت صعب الخالي من الدسم.

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

Answer 6

فقط بعض الملاحظات:

تعليقات هامة عن كل ما يمكن استنتاجه بسهولة من رمز (على سبيل المثالخوارزميات رياضية معقدة).

مشاكل مع التعليقات هو أنها تحتاج إلى الحفاظ عليها مثل قانون ولكن في كثير من الأحيان لا يتم الاحتفاظ في كل شيء.

أنا لا أحب مثل هذه التعليقات:

// Create the "Analyze" button
Button analyzeButton = new Button();
analyzeButton.Text = "Analyze";
analyzeButton.Location = new Point( 100, 100 );
Controls.Add( analyzeButton );

أفضل:

CreateAnalyzeButton();


void CreateAnalyzeButton()
{
    Button analyzeButton = new Button();
    analyzeButton.Text = "Analyze";
    analyzeButton.Location = new Point( 100, 100 );
    Controls.Add( analyzeButton );
}

الآن مدونة تحكي القصة كاملة.لا حاجة للتعليق.

Answer 7

أعتقد أن هذا يعتمد على السيناريو.

الأساليب/وظائف/دروس يجب وصف قصير ماذا يفعلون وكيف يفعلون ذلك ، ما يأخذون وما عودتهم ، إن لم يكن واضحا على الفور و التي عادة (في قانون بلدي) يأتي في شكل جافادوك-أسلوب تعليق كتلة.

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

Answer 8

استخدام الوسم البحث وستجد لذلك لديه كومة من النقاش حول تعليقات التعليمات البرمجية بالفعل:

https://stackoverflow.com/questions/tagged/comments

وتعليقا رمز

Answer 9

إلقاء نظرة على رمز كاملة.ببساطة أفضل على مثل هذه المواضيع.