دعني أخبرك سراً: إذا أردت أن تعرف معنى التجهُّم فأخبر مبرمجاً أنه يجب عليه التعليق على جميع أجزاء شفرته البرمجية وراقب وجهه.🙂
عفواً، في الخدمة دائماً.
إن كُنت لا تعلم ما هي التعليقات، فهي أسطرٌ يكتبها المبرمج في داخل شفرته البرمجية من أجل توضيح أو توثيق أو شرح شفرته البرمجية، وتُوجدُ أهدافٌ أخرى بعضُها طريف، وهو ما ستراهُ في نهاية هذه التدوينة.
التعليقات يا عزيزي لا تؤثر على تنفيذ البرنامج الذي تُكتب به، فأثناء تنفيذ البرنامج يتم تجاهلها كأنها لا تُوجد، وهي تُكتب بطُرقٍ مختلفة.
[divider style=”dashed” top=”20″ bottom=”20″]
كيف تكتب تعليقاً في لغة برمجة
كلُّ كلمة تكتب في ملف الشفرة البرمجية تُعتبر شيئاً ذا أثر على تنفيذ المشروع كما ذكرتُ لك، عدا التعليقات، لذا يجب أن تُكتب هذه التعليقات بطريقة تجعلُها مميزة تماماً ليستطيع المترجم التعرُّف عليها.
دعني أريك 3 طرق مختلفة لكتابة التعليقات في لغاتِ برمجةٍ مختلفة.

مثلاً في HTML لكتابة تعليق يجبُ أن يحاط التعليق بعلامات، قبل البدء <!– وبنهاية التعليق –> شاهد المثال التالي
<!--Some comment-->
وفي لغة جافا من الممكن كتابة التعليق في سطر واحد أو أسطرٍ متعددة، ولكل منهما طريقتُه الخاصة.
فلكتابة تعليق في سطرٍ واحد يجب أن تبدأ السطر بـ // كما ترى أدناه
// one line comment
أما لكتابة تعليق في أسطر متعددة فيجب أن تبدأ التعليق بـ /* وينتهي بـ */ ، شاهد المثال وبالمثال يتضح المقال
/* * first line comment could be long * second line comment, ... etc */
الأمرُ بسيط أليس كذلك؟ ولكن لهُ فوائدُ متعددة كما سترى الآن.
[divider style=”dashed” top=”20″ bottom=”20″]
ماذا تستفيد من كتابة التعليقات؟
برغم بساطة الأمر جداً، فهو يبدو وكأنه بضعة أسطر يكتب فيها المبرمجُ شيئاً ما ثم يواصلُ عمله البرمجي، ولكن هذه الأسطر قد تكونُ لها فوائد أكبر مما تتخيل، اقرأ هذه الفوائدة العظيمة معي:
[tie_list type=”thumbup”]
- كتابة التعليقات قد تساعد في تصميم البرنامج وبناء الهيكل العام له.
- كتابة التعليقات قد تقلل من تكاليف صيانة مشروع كامل لنسبةٍ قد تزيدُ عن 50% وفق تجربتي الشخصية.
- سرعة اندماج المطورين في برمجة الشفرات البرمجية الموثقة أعلى بكثير عن غير الموثقة.
- سهولة إحلال واستبدال المبرمجين والشركات عند توثيق البرامج.[/tie_list]
فكما ترى قد تكونُ الفوائد برمجية أو مالية، حاليّة أو مستقبلية، وهناكَ فوائد أخرى حتماً قد تكون المقروئية احدها. اطلع على هذه التدوينة إستخدم المقروئية أو ضيّع سنوات البرمجة.
تجد في صور الأكواد أمثلة للتعليقات [divider style=”dashed” top=”20″ bottom=”20″]
لماذا لا يُحب المبرمجون كتابة التعليقات؟
برغم اختلاف وجهات النظر، لكني أرى أن هناك سببين رئيسيين لتحاشي المبرمجين كتابة التعليقات:
- عدم معرفة أهمية التوثيق وآثاره.
- أنهم لا يحبون التوثيق.
المبرمجون عموماً أناسٌ عمليون جداً، يفضلون قضاء الوقت في شيءٍ لهُ أثرٌ واضح ولا يفضلون كثرة الحديث والتواصل مع الناس، هذه طبيعةُ عملهم، ومع طول الانغماس في هذا الروتين يصبح ذلك جزءاً من شخصيتهم.
شخصياً عانيتُ من هذا الأمر لفترة وتطلب الأمر جهداً كي أتغلب عليه… ربما أتحدث عنه في وقت لاحق.
على كُلٍ السببُ الثاني هو السببُ الأكثرُ شيوعاً لدى المبرمجين، فكجزءٍ من شخصيتهم يرون أن الكلمات التي لن تؤثر في سير عمل البرنامج لا داعي لكتابتها. بهذه البساطة.
يكتب المبرمج مئات أو آلاف الكلمات يومياً هذا خلا عن رؤيتهم لكتابة التعليقات والتوثيق بأنّه مضيعةٌ لوقتهم وجهدهم الثمين والذي من الممكن أن يستثمر في كتابة البرنامج التالي.. نظرة منطقية إلى حد ما..
ولكن…
الواقعُ يقول أن أفضل من يكتب التعليقات هو من كتب الشفرة البرمجية، ولا بديل لذلك حتى الآن.. للأسف أخي المبرمج.
[divider style=”dashed” top=”20″ bottom=”20″]
هل هناك معيار للتعليقات
عند الالتحاق ببيئات عملٍ مختلفة ستلاحظ أن نسق التوثيق -إذا كانوا يوثقون برامجهم- مختلفٌ بين كل بيئة وأخرى. هذا يجعلُك تتسائل.. هل يوجدُ معيارٌ موحّد Standard للتوثيق؟!!
الحقيقةُ هي -بعد البحث- لا يوجد معيارٌ موحّد، لذلك تجد أن معيار التوثيق في البيئات المنظمة يُتفق عليه من قبل فريق العمل وأحياناً يتم تحديده من قبل مهندس المشروع the architect.
ما يقوله المبرمج عبر تعليقه الأمر المهم أن يكون التوثيق ذو فائدة وواضحاً بحيث يشرح الشفرة البرمجية الموجودة ومنطق العمل بصورة عامة.
[divider style=”dashed” top=”20″ bottom=”20″]
أغرب وأطرف تعليق قرأته
كما تعلم عزيزي أن كتابة الشفرات البرمجية لوقت طويل يعني أنك قد كتبتها في جميع أوقات اليوم، صباحَ مساء، فجراً سحراً ظهراً. وهذا بالتأكيد يعني أنك -إذا كنت توثُّق برامجك- أنك قد كتبت تعليقات في حالات نفسية مختلفة.
من أغرب وأطرف التعليقات التي مرّت عليّ هو ما قرأته عن أحد المبرمجين -لا أذكر اسمه- يقول فيما معناه أو قريباً منه:
يا أنا في المستقبل، أعلمُ أنك ستعودُ إلى قراءة هذا الجزء من الشفرة البرمجية وستقرأ هذا التعليق، كما أعلم أنك لن تستطيع فهم الشفرة البرمجية هذه. أنا أحذُّرك من التعديل على هذه الشفرة البرمجية وأنصحك بتركها كما هي. مبرمج مجهول
مبرمج مجهولتعجّبتُ من الحالةِ التي كتبَ فيها هذا التعليق، توقّعتُ أنهُ سيكون نص نائم أو في قمة الإنهاك، والغريب في الأمر أنهُ ترك الشفرة البرمجية كما هي واستجاب للتهديد 🙂
[divider style=”dashed” top=”20″ bottom=”20″]
والآن أخي الكريم، هلّا شاركتنا رأيك وتجربتك عن التعليقات أثناء البرمجة؟
هل تفضلها؟ ما هو اسلوبك؟ هل تستفيد مما كتبه المبرمجون السابقون من تعليقات؟
لا تنسى مشاركة التدوينة
شكرا على الموضوع القيم
صراحة التوثيق بالنسبة لي مهم جدا خصوصا ان كان المشروع كبير
أو ان أردت طرح السورس للتطوير يجب ان يفهم المطور ماذا كتبت
وفي كثير من الاحيان السورس الذي لا يحتوي على تعليقات يبقى مجرد اسطر غامضة صعبة الفهم.
جميل أن تستخدم التوثيق سعيد، وعجيب أن يكون التوثيق بحاجة إلى توثيق آخر 🙂
سعدتُ بوجودك ?
دون شك اخي العزيز …
ان للتعاليق قيمة كبيرة لي ولمن سيستمر بالعمل من بعدي في مشروع واحد وكما ذكر الإخوان سابقا فهي تساعد في عمليات كثيرة من ناحية الصيانة والتعديل وغيره
كما تعد اداء فعالا في التوجيه
وشكراً ,,,
من الجميل أن تفكيرك ممتد إلى النظرة المستقبلية، حين يعمل على الشفرة المصدرية أحدٌ غيرك.
يبدو أنك من النادرين. كُن كذلك ?
التعليقات مهمة جدا حتي وإن كنت ابرمج وحدي
تساعد في تسريع عملية التعديل علي الشيفرة البرمجية إذا كان هنالك خطأ ما
وعن تجربة أفضل كتابة التعليقات
ووشكرا
عند مراجعة الشفرة البرمجية وخصوصاً عند الأخطاء يكون وجود الشفرات البرمجية كمثل الهدايا على الطريق كما ذكرتم 🙂
شكراً لك محمد على تواجدك معنا في علوم.
الحقيقة اني قد برمجة كثيراً وعرفة قيمة التوثيق وكيف انه ساعدني كثير في اشياء كثيرة منها .
1- سهولة عمل الصيانة للانظمة والوصول السريع الى مكان الاخطاء (كيف يحدث انه يساعدك في الصيانة طبعاً نحن كمبرمجين نفهم ايش الخط المنطق او اين حصل بالذات وما السبب الذي ادى الى هذا بالذات اذا كنت انا من برمج هذا الشفرة وللوصول الية بسرعة استخدم التعليقات التي تشرحي عمل الشفرات بدل ان اتفحص الكود كامل للوصول الى هذة الشفرة .
2- سهولة وسرعة عمل التطوير للبرنامج لانه عندما ابدء بعمل التطوير اظر لفهم الكود السابق من جيد لاتذكرة وايضا لفهم كمية الشفرات التي احتاجة لعمل التطوير واين ابدء التطوير فمن خلال التعليق افهم ما عمل كل داله بسرعة ولا اطر لفحص الكود كاملا من جديد .
3- سهولة التسليم عند الخروج من اي شركة تعمل فيها فانت لست مطر لتفحص الكود من جديد وبذل جهد كبير ف تسليم اعمالك وشرحة للمختصين.
4- التعليقات عملتني اشياء كثيرة في حياتي واهم شي التنظيم وعدم العشوائيات في الحياة العامة .
اتمني انن يفيدكم راي المختصر .
من أفضل التعليقات في مدونة علوم، شكراً لمشاركتنا تجربتك وخبراتك أخي حسن.
التعليقات مهمه جدا عند العمل مع مجموعة مبرمجيين
حقيقة مُجرّدة