Comments in Dart

التعليقات هي أجزاء من الكود يتم تجاهلها من قبل المترجم (compiler) وتستخدم لشرح الكود أو إضافة ملاحظات للمطورين. في Dart، هناك ثلاثة أنواع رئيسية من التعليقات:

1. التعليقات أحادية السطر (Single-line comments)

تبدأ بعلامة // وتستمر حتى نهاية السطر.

// هذا تعليق أحادي السطر
void main() {
  print('Hello, World!'); // يمكن وضع التعليق بعد الكود
}

2. التعليقات متعددة الأسطر (Multi-line comments)

تبدأ بعلامة /* وتنتهي بعلامة */ ويمكن أن تمتد على عدة أسطر.

/*
 هذا تعليق متعدد الأسطر
 يمكن أن يحتوي على عدة جمل
 وتنسيقات مختلفة
*/
void main() {
  print('Hello, World!');
}

3. تعليقات التوثيق (Documentation comments)

تبدأ بعلامة /// أو /** وتستخدم لتوثيق الكود (يمكن استخراجها بواسطة أدوات مثل dartdoc).

أ. باستخدام ///:

/// حساب مربع العدد
/// 
/// [number] العدد المراد حساب مربعه
/// 
/// إرجاع [int] مربع العدد المدخل
int square(int number) {
  return number * number;
}

ب. باستخدام /** */:

/**
 * حساب مجموع عددين
 * 
 * @param a العدد الأول
 * @param b العدد الثاني
 * @return مجموع العددين
 */
int sum(int a, int b) {
  return a + b;
}

استخدامات متقدمة للتعليقات:
1. تعليقات التوثيق مع Markdown:

/// # مثال على دالة الجمع
/// 
/// هذه الدالة تقوم بجمع عددين:
/// 
/// ```dart
/// final result = sum(2, 3); // 5
/// ```
/// 
/// **ملاحظة**: لا تدعم الأعداد العشرية
int sum(int a, int b) => a + b;

2. تعليقات TODO:

// TODO: تحسين الأداء في الإصدارات القادمة
void processData() {
  // ...
}

3. تعليقات لتعطيل أجزاء من الكود:

void main() {
  print('هذا الكود يعمل');
  /*
  print('هذا الكود معطل مؤقتا');
  print('لأغراض التصحيح');
  */
}

نصائح لكتابة تعليقات فعالة:

1. اكتب تعليقات توضح “لماذا” وليس “ماذا”: الكود نفسه يوضح ما يحدث، التعليقات يجب أن تشرح لماذا تم كتابته بهذه الطريقة.
2. تجنب التعليقات الواضحة.
3. حدّث التعليقات عند تحديث الكود: التعليقات القديمة التي لا تطابق الكود الحالي يمكن أن تكون مضللة أكثر من عدم وجود تعليقات.
4. استخدم تعليقات التوثيق للواجهات العامة: خاصة عند بناء مكتبات أو APIs سيستخدمها آخرون.
5. استخدم TODO للتحسينات المستقبلية: ولكن لا تتركها إلى الأبد! حدد موعدًا لمعالجتها.

التعليقات الجيدة تجعل الكود أكثر قابلية للقراءة والصيانة، خاصة عند العمل في فريق أو عند العودة للكود بعد فترة طويلة