معني - social comments




كيف تحب تعليقاتك؟ (6)

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


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

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

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


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


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


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

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

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


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


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

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

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

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

// 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 );
}

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