إضافة التعليقات في الشفرة

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

الاجمل من ذلك ان تكون الشفرة هي تشرح نفسها بنفسها، ولا تحتاج الا الجزء اليسير من التعليقات

مثلا "احيانا" اسمي همممم الـ "فعل" "method" هكذا:

اجلب-لي-دجاجتي-السمينة-من-بيت-الدجاج-واحضرها-لهنا-لكي-احضرها-واضعها-في-الفرن-الالي-الذي-يجب-ان-يكون-بدرجة-حرارة-....

اعتمد على فكرة: انا اعمل مبرمج لاكتب تطبيق "code" ليس لاكتب تعليقات، التعليقات اكتبها عندما يكون الصف "class" او همممم الفعل "actoin/method" غير واضحين

في غالب أحاول تجنب كتابة التعليقات و ذلك بجعل الشفرة مقروءة بشكل أكبر ,و في بعض الاحيان أترك رؤوس أقلام لنقاط التي قد تكون غامضة و آخرى تحذيرات لشفرة قد تستخدم بشكل خاطئ و أيضا لقائمة المهام (TODO).

أكتبها بشكل مفصل عندما أريد إنشاء توثيق لشفرة باستخدام أحد ادوات لإنشاء التوثيق ( javadoc , pydoc) بتنسيقات مختلفة مثل HTML أو غيرها

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

أنا شخصيا أستخدم صيغة DocBlock والتي تجدون شرحا مختصرا لها هنا في هذه الصفحة:

السبب الرئيسي الذي يدعوني إلى ذلك هو سهولة توليد توثيق للشيفرة البرمجية إنطلاقا من التعليقات المسجلة وفق هذه الصيغة، في حالة لغة PHP أستخدم برنامج phpDocumentor وصفحته الرئيسية على الشابكة (الإنترنت) هي:

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

هل تعرف أن بعض المدراء في الشركات العربية يجبر المبرمج على عدم كتابة أي تعليق على الكود !! ظناً منه ان ذلك يحمي سرية محتوى الكود عند تسربه للخارج ؟

فيضل كلما اراد أن يفهم كود لمبرمج أخر ان يستدعيه ليشرحه له !! حتى ولوكان في جزر الواق واق !!

بالنسبة لي كتابة التعليقات على الكود امر ممل و يطيل مدة العمل ويقلل من الانتاجية خاصة انني اعمل لوحدي وليس في فريق عمل ..

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