هل يجب تطبيق تعليقات الطريقة/الفصل باستمرار أو على أساس الحاجة فقط؟

Question

من أجل الاتساق ، قمت دائمًا بتطبيق التعليقات (في شكل Javadoc) على جميع الأساليب والفصول ، حتى لو كانت أساليب Getters و Setters بسيطة أو فصول غلاف صغيرة جدًا. لكنني أسعى أيضًا إلى كتابة التعليمات البرمجية الموثقة الذاتي التي تجعل التعليقات غالبًا ما تكون ضرورية ؛ أي كتابة التعليقات فقط عند الحاجة (وقبل القيام بذلك ، حاول إعادة كتابة الرمز حتى لا تحتاج إلى التعليق على الإطلاق). وبالتالي ، يبدو أن هذين النهجين متناقضان مع بعضهما البعض.

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

Answer 1

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

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

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

Answer 2

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

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