الجزء الثاني عشر – أفضل الممارسات في البرمجة – سلسلة FSWD – PHP

أولاً: التوثيق (Documentation)

التوثيق هو أحد العوامل الأساسية التي تساعد المطورين على فهم الكود الذي كتبوه أو كتبه الآخرون. توثيق الكود يعد جزءًا مهمًا من عملية الصيانة (Maintenance) ويُسهل على فرق التطوير التفاعل مع النظام بشكل أكثر فاعلية.

لماذا التوثيق مهم؟

1. يساعد المطورين على الفهم بسرعة: عندما يعود المطور للعمل على الكود بعد فترة طويلة، يكون التوثيق مرشدًا لفهم كيفية عمل الكود.

2. يسهل التعاون بين الفرق: عندما يتعاون عدة مطورين على نفس المشروع، يساعد التوثيق في جعل الكود أكثر وضوحًا ويفهمه الجميع.

3. يساهم في تسريع عملية الصيانة والتطوير: عندما يكون الكود موثقًا بشكل جيد، يصبح من الأسهل تعديل الكود، إضافة ميزات جديدة، أو إصلاح الأخطاء.

كيفية توثيق الكود بشكل جيد:

1. التعليقات (Comments):
   يجب أن تكون التعليقات في الكود موجزة ومباشرة. التعليق يجب أن يشرح “لماذا” يتم تنفيذ شيء ما في الكود وليس “ماذا” يقوم به الكود (لأن الكود نفسه يوضح ذلك).

   أمثلة:

   • تعليق على دالة

// دالة للتحقق من صحة البريد الإلكتروني
function isValidEmail($email) {
    return filter_var($email, FILTER_VALIDATE_EMAIL);
}

تعليق على كتلة منطقية:

// تحقق إذا كان المستخدم قد سجل الدخول
if (!isset($_SESSION['user_id'])) {
    // إعادة التوجيه إلى صفحة تسجيل الدخول
    header('Location: login.php');
    exit();
}

**التوثيق باستخدام DocBlocks:
في العديد من لغات البرمجة، يمكن استخدام DocBlocks (تعليقات خاصة بالتوثيق) لتوثيق الدوال أو الكائنات. هذه التوثيقات تستخدم لتعريف أنواع المتغيرات، نوع القيمة المرجعية، ووصف الوظيفة.

مثال

/**
 * دالة لحساب مجموع الأرقام في مصفوفة
 *
 * @param array $numbers - مصفوفة من الأرقام
 * @return int - مجموع الأرقام
 */
function sumNumbers(array $numbers) {
    $sum = 0;
    foreach ($numbers as $number) {
        $sum += $number;
    }
    return $sum;
}

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

• توثيق الأخطاء والاستثناءات (Error Handling):
  من المهم توثيق أي استثناءات أو أخطاء محتملة قد تحدث أثناء تنفيذ الكود. يمكن أن يساهم التوثيق هنا في معرفة كيفية التعامل مع هذه الحالات.

  مثال

/**
 * دالة لتحميل ملف وتحويله إلى مصفوفة
 *
 * @param string $filename - اسم الملف
 * @return array - البيانات الموجودة في الملف
 * @throws Exception - إذا لم يتم العثور على الملف أو حدث خطأ أثناء القراءة
 */
function loadFile($filename) {
    if (!file_exists($filename)) {
        throw new Exception("الملف غير موجود: " . $filename);
    }

    return file($filename, FILE_IGNORE_NEW_LINES);
}

ثانيًا: الصيانة والأداء (Maintenance and Performance)

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

1. الصيانة (Maintenance)

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

أفضل الممارسات لكتابة كود قابل للصيانة:

1. التنظيم الجيد (Code Organization):
   يجب تقسيم الكود إلى وحدات صغيرة (functions, classes, etc.) تتعامل مع وظيفة محددة وواضحة. كما يجب فصل منطق العمل عن واجهات المستخدم (separate business logic from presentation logic).

   • مبدأ SOLID: يمكن اتباع مبادئ SOLID لتصميم كود قابل للتوسيع والتطوير، مثل:

     • Single Responsibility Principle (مبدأ المسؤولية الواحدة): كل وحدة (مثل الكلاس) يجب أن تكون مسؤولة عن مهمة واحدة فقط.

     • Open/Closed Principle (مبدأ الفتح والإغلاق): يجب أن تكون الكودات قابلة للتوسيع ولكن مغلقة للتعديل.

2. التسمية الواضحة:
   يجب أن تكون أسماء المتغيرات والدوال والكائنات ذات دلالة واضحة على وظيفتها. لا تترك أي مجال للغموض.

   • أسماء دوال واضحة

function getUserByEmail($email) {
    // إرجاع المستخدم باستخدام البريد الإلكتروني
}

• إعادة استخدام الكود:
  عند الكتابة، حاول أن تجعل الكود قابلاً لإعادة الاستخدام بدلاً من تكرار نفس الشيفرة عدة مرات. يمكن تحقيق ذلك باستخدام الدوال أو الكائنات أو الحزم الخارجية.

• الاختبارات (Testing):
  كتابة اختبارات وحدات (Unit Tests) من أفضل الممارسات التي تساعد في الصيانة. باستخدام اختبارات الوحدات، يمكنك التأكد من أن التغييرات التي تجريها في الكود لا تؤدي إلى مشاكل في النظام.

  • أداة PHPUnit: هي أداة مشهورة لاختبار تطبيقات PHP.

  • مثال اختبار وحدة

class UserTest extends PHPUnit\Framework\TestCase {
    public function testUserIsValid() {
        $user = new User("Ahmed", "ahmed@example.com");
        $this->assertTrue($user->isValid());
    }
}

1. الشفافية والتوثيق المستمر:
   تأكد من تحديث التوثيق بشكل دوري بعد إضافة ميزات أو تعديل الكود. التوثيق الجيد يسهل العمل الجماعي ويجعل من السهل العودة إلى الكود في المستقبل.

2. الأداء (Performance)

الأداء يعني السرعة و الكفاءة التي يعمل بها الكود. لتحسين أداء الكود، يجب أن تكون على دراية بكيفية التعامل مع الموارد مثل الذاكرة و الوقت.

أفضل الممارسات لتحسين الأداء:

1. تقليل التكرار:
   تجنب تكرار الكود إذا كان يمكن تحقيق نفس الهدف باستخدام دالة أو كلاس يمكن إعادة استخدامه.

2. تحسين الاستعلامات (Database Queries):

   • استخدام الاستعلامات المحسّنة: تأكد من أن استعلامات SQL التي تستخدمها في التطبيق محكمة وفعّالة.

   • استخدام الفهارس (Indexes) في قاعدة البيانات لتحسين سرعة الاستعلامات.

   • الاستعلامات المجمعة (Batching): بدلاً من إرسال العديد من الاستعلامات الفردية، حاول تجميعها في استعلام واحد.

3. التخزين المؤقت (Caching):

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

   • يمكنك استخدام Memcached أو Redis كأنظمة تخزين مؤقت.

4. تحسين استخدام الذاكرة:
   تأكد من أن البرنامج لا يستخدم ذاكرة أكبر من المطلوب. استخدم المرجعية بالأصغر حيثما أمكن (مثل استخدام المتغيرات الصغيرة بدلًا من كائنات ضخمة).

5. إجراء التحسينات على مستوى الكود:

   • استخدام العوامل المنطقية بشكل ذكي: مثلا عند استخدام العوامل && و ||، تأكد من ترتيبهم بطريقة تحقق أولاً الشرط الذي من المرجح أن يوقف العملية.

   • تجنب استخدام الحلقات المتداخلة الثقيلة (nested loops) بقدر الإمكان.

ملخص:

1. التوثيق:

   • استخدم التعليقات بشكل مناسب لتوضيح الكود.

   • استخدم DocBlocks لتوثيق الدوال والمكتبات.

   • وثّق الأخطاء والاستثناءات لتسهيل صيانة الكود.

2. الصيانة:

   • اتبع مبادئ SOLID لتنظيم الكود.

   • احرص على الكتابة باستخدام أسماء دوال واضحة.

   • اكتب اختبارات وحدات (Unit Tests) لضمان جودة الكود.

3. الأداء:

   • حافظ على استعلامات فعّالة في قاعدة البيانات.

   • استخدم التخزين المؤقت لتقليل أوقات الاستجابة.

   • قلل التكرار في الكود لتحقيق أداء أفضل.