فكرة وواقع التعليقات في لغات البرمجة

دعني أخبرك سراً: إذا أردت أن تعرف معنى التجهُّم فأخبر مبرمجاً أنه يجب عليه التعليق على جميع أجزاء شفرته البرمجية وراقب وجهه.🙂

عفواً، في الخدمة دائماً.

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

التعليقات يا عزيزي لا تؤثر على تنفيذ البرنامج الذي تُكتب به، فأثناء تنفيذ البرنامج يتم تجاهلها كأنها لا تُوجد، وهي تُكتب بطُرقٍ مختلفة.

[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″]

  لماذا لا يُحب المبرمجون كتابة التعليقات؟

  برغم اختلاف وجهات النظر، لكني أرى أن هناك سببين رئيسيين لتحاشي المبرمجين كتابة التعليقات:

  1. عدم معرفة أهمية التوثيق وآثاره.
  2. أنهم لا يحبون التوثيق.

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

  شخصياً عانيتُ من هذا الأمر لفترة وتطلب الأمر جهداً كي أتغلب عليه… ربما أتحدث عنه في وقت لاحق.

  على كُلٍ السببُ الثاني هو السببُ الأكثرُ شيوعاً لدى المبرمجين، فكجزءٍ من شخصيتهم يرون أن الكلمات التي لن تؤثر في سير عمل البرنامج لا داعي لكتابتها. بهذه البساطة.

  

  هذا خلا عن رؤيتهم لكتابة التعليقات والتوثيق بأنّه مضيعةٌ لوقتهم وجهدهم الثمين والذي من الممكن أن يستثمر في كتابة البرنامج التالي.. نظرة منطقية إلى حد ما..

  ولكن…

  الواقعُ يقول أن أفضل من يكتب التعليقات هو من كتب الشفرة البرمجية، ولا بديل لذلك حتى الآن.. للأسف أخي المبرمج.

  [divider style=”dashed” top=”20″ bottom=”20″]

  هل هناك معيار للتعليقات

  عند الالتحاق ببيئات عملٍ مختلفة ستلاحظ أن نسق التوثيق -إذا كانوا يوثقون برامجهم- مختلفٌ بين كل بيئة وأخرى. هذا يجعلُك تتسائل.. هل يوجدُ معيارٌ موحّد Standard للتوثيق؟!!

  الحقيقةُ هي -بعد البحث- لا يوجد معيارٌ موحّد، لذلك تجد أن معيار التوثيق في البيئات المنظمة يُتفق عليه من قبل فريق العمل وأحياناً يتم تحديده من قبل مهندس المشروع the architect.

  

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

  [divider style=”dashed” top=”20″ bottom=”20″]

  أغرب وأطرف تعليق قرأته

  كما تعلم عزيزي أن كتابة الشفرات البرمجية لوقت طويل يعني أنك قد كتبتها في جميع أوقات اليوم، صباحَ مساء، فجراً سحراً ظهراً. وهذا بالتأكيد يعني أنك -إذا كنت توثُّق برامجك- أنك قد كتبت تعليقات في حالات نفسية مختلفة.

  من أغرب وأطرف التعليقات التي مرّت عليّ هو ما قرأته عن أحد المبرمجين -لا أذكر اسمه- يقول فيما معناه أو قريباً منه:

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

  مبرمج مجهول

  تعجّبتُ من الحالةِ التي كتبَ فيها هذا التعليق، توقّعتُ أنهُ سيكون نص نائم أو في قمة الإنهاك، والغريب في الأمر أنهُ ترك الشفرة البرمجية كما هي واستجاب للتهديد 🙂

  [divider style=”dashed” top=”20″ bottom=”20″]

  والآن أخي الكريم، هلّا شاركتنا رأيك وتجربتك عن التعليقات أثناء البرمجة؟

  هل تفضلها؟ ما هو اسلوبك؟ هل تستفيد مما كتبه المبرمجون السابقون من تعليقات؟

  لا تنسى مشاركة التدوينة