التعليقات (Comments)
اذهب إلى التنقل
اذهب إلى البحث
توصيف المشكلة
وجود الكثير من التعليقات في التوابع (methods) بهدف الشرح التفصيليّ للشيفرة.
أسبابها
غالبًا ما يكون السبب منطقيًّا لإضافة التعليقات وخاصّة عندما تكون الشيفرة مبهمةً غير واضحة، لكن بهذه الحالة لن نعدَّ تلك التعليقات إلا محاولاتٍ بائسةً لتغطية الشيفرة الرديئة بجانبها! ولتكن القاعدة:
إنّ أفضل تعليقٍ يمكن أن تضيفه هو تسمية التوابع (methods) والأصناف (classes) تسميةً جيّدةً معبِّرة.
وإذا ما وجدتَ أن الشيفرة لن تكون واضحةً بحذف التعليقات المُضافة، فمن المُؤسف القول بضرورة تغيير بُنيتها (structure) إلى الشكل الذي يمكِّن من الاستغناء عن التعليقات.
وما الحل؟
- إذا كانت التعليقات لشرح التعابير المعقَّدة فيجب تقسيم التعبير الواحد إلى تعابيرَ فرعيّة (subexpressions) بالاعتماد على استخراج المتغيِّرات (extract variables).
- وإن كانت لشرح مقطعٍ (section) من الشيفرة فمن الممكن عزل ذلك المقطع في تابعٍ (method) جديدٍ باسمٍ معبِّر (مأخوذٍ غالبًا من التعليقات ذاتها).
- فإن استمرَّت الحاجة للتعليقات لشرح ما يقوم به التابع الناتج عن المحاولة السابقة فمن المهمّ حينئذٍ إعادة تسمية التابع (rename method) لاسمٍ يشرح ذاته بذاته.
- عند التأكيد على القواعد المهمّة في حالةٍ من الحالات والضروريّة لعمل النظام بشكلٍ صحيحٍ، فالحلُّ يكمُن بإضافة التأكيدات (add assertions).
إليك المزيد
ستحصل بحلِّ المشكلة على شيفرةٍ أكثر وضوحًا وقراءةً.
تجاهل المشكلة
تصبح التعليقات مفيدةً ويمكن إبقاؤها لتوضيح:
- السبب بتنفيذ (implement) جزءٍ ما من الشيفرة بالطريقة التي كُتبت بها.
- الخوارزميات المعقَّدة (عندما لا تُجدي كافّةُ الأساليب السابقة للتبسيط).
انظر أيضًا
- استخراج المتغيِّرات (extract variables)
- استخراج التابع (extract method)
- إعادة تسمية التابع (rename method)
- إضافة التأكيدات (add assertions)