سهل الصيانة

نضمن أن هيكل المجلد هو أول شيء سيحكم عليه المطور المستقبلي. يتم استخدام هياكل مجلدات متسقة وذات آراء (مثل src/components، src/services، src/hooks، src/features).

نكتب الكود للبشر، وليس فقط للمترجم. يتم اتباع تقاليد وأشكال تسمية متسقة في جميع المشاريع. يتم إعداد ESLint وPrettier لفرض التنسيق عبر أدوات ما قبل الالتزام مثل Husky، مما يضمن جودة الكود من البداية. نحن نفضل اللغات الموجهة، باستخدام TypeScript بدلاً من JavaScript لتحسين الصيانة. نحن دائمًا نحافظ على الكود قابلاً للقراءة والإدارة، مركزًا وصغيرًا.

نتجنب فوضى التصميم عن طريق ترميز قرارات التصميم في مكونات كود قابلة لإعادة الاستخدام. يتم استخدام أنظمة مكونات راسخة مثل ShadCN وTailwind UI أو Material UI لضمان الاتساق عبر المشاريع. تساعد هذه الطريقة في تجنب كتابة كود واجهة مستخدم لمرة واحدة إلا إذا كان ذلك ضروريًا للغاية، مما يوفر الوقت ويضمن اتساق التصميم.

نحن نضمن أن منطق الأعمال لا ينتمي أبداً إلى طبقة واجهة المستخدم. يتم استخدام طبقات الخدمة، أو الخطافات المخصصة، أو وحدات التحكم لعزل وتنظيم منطق الأعمال بشكل صحيح. بالنسبة لتفاعلات واجهة برمجة التطبيقات، يتم تنفيذ أنماط جلب البيانات الحديثة باستخدام SWR، React Query، أو تغليفات مخصصة تتعامل مع التخزين المؤقت وحالات الأخطاء بكفاءة. يتم تجريد جميع استدعاءات واجهة برمجة التطبيقات إلى مجلدات خدمة مخصصة، مثل services/api/user.ts، مما يجعل قاعدة الشيفرة أكثر قابلية للصيانة والاختبار.

نحن لا نكتب روايات—فقط ما يكفي لتوجيه المطور التالي بسرعة. يتم دائماً كتابة README.md مع إعداد، متغيرات البيئة، تعليمات النشر. يتم إضافة تعليقات قصيرة للمنطق المعقد (لا تفرط في التعليق). يتم استخدام TSDoc / JSDoc للطرق العامة. يتم إضافة CONTRIBUTING.md لكيفية تشغيل الاختبارات / الاتفاقيات.

لا نحتاج إلى تغطية 100%، ولكننا بحاجة إلى تغطية كاملة حيث يكون الفشل مكلفاً. يتم إعطاء الأولوية للاختبارات الوحدوية للوظائف الحيوية للأعمال. يتم استخدام اختبارات التكامل لنقاط نهاية واجهة برمجة التطبيقات أو سير العمل. يتم اختيار أدوات سهلة الاستخدام: Jest + Testing Library (React)، Playwright للاختبارات الشاملة. حتى نتمكن من الحفاظ على توازن بين التغطية ووقت الوصول إلى السوق.

كل عملية دفع تثير فحوصات السلامة. تم إعداد خط أنابيب CI/CD بسيط يقوم بـ: فحوصات النوع (مثل، tsc --noEmit)، فحوصات التنسيق/التنسيق، اختبارات وحدوية، نشر تلقائي إلى بيئة الاختبار. يتم استخدام أدوات شائعة: GitHub Actions، Docker Compose.

نتجنب أي شيء مشفر بشكل ثابت = ألم على المدى الطويل. يتم تخزين جميع الأسرار/التكوين في .env أو تكوين بعيد (مثل، AWS SSM، بيئات Vercel). يتم استخدام إعداد قائم على البيئة (process.env.NODE_ENV). يتم تجنب دفع .env.*، مفاتيح واجهة برمجة التطبيقات، بيانات الاعتماد، إلخ. وهي موثقة بشكل جيد.