أهمية كتابة التعليقات داخل الكود ؟

مرحبًا،

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

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

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

رغم ذلك يتم في بعض المشاريع القيام بشرح تفصيلي لاستعمال بعض الأدوات التي تقوم بإنشاء التوثيق بناء على التعليقات.

بالمختصر، عليك إضافة تعليقات لجعل الكود أوضح، و لكن أبقها مختصرة قدر الإمكان.

تحياتي.

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

// تعيد عدد الأيام بين تاريخين معينين
function calculateDaysBetween($startDate, $endDate) {
    //...
}

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

عندما يقوم المبرمجون بكتابة تعليق في الكود باستخدام // فهذا ما يسمى بالتعليق (comment) وتختلف علامة التعليق من لغة برمجة إلى أخرى . والتعليقات هي نص لا يتم تنفيذه من قبل الشيفرة بل يستخدمه المطورون لإخبار أشياء عن الكود للمطورين الأخرين أو لأنفسهم في المستقبل وهذا لفهم الكود بشكل أفضل حيث هذه التعليقات تساعد على توضيح غرض الكود أو تفاصيله.

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

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

وأيضا يتوجب كتابة تعليقات إذا كان هناك جزء مفقود في الكود . حيث يوجد ما يسمى TODO وهذه الكلمة متفق عليها وتشير إلى أن الكود ينقصه شئ ولكنه لم يتم إنشاءه حتى الآن وهي تكون إضافات أو خصائص جديدة لم يتم إنشاءها أو يجب تحسين الكود الحالي . لهذا إذا كان لديك كود تريد تحسينه في المستقبل أو إضافة خاصية جديدة يرجى كتابة TODO هكذا مثلا :

// TODO: New Feature must be added

وهكذا تقوم بشرح الذي يجب عمله بعد TODO .

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

وأيضا يجب عليك أن تكون مختصرا في كتابة التعليقات ولا تقم بكتابة نصوص كبير.