Coroid يستخدم تطوير يعتمد على المواصفات: تظل المواصفة مرتبطة بكل مهمة من مرحلة التخطيط وحتى الاختبار والمراجعة، بحيث تعمل جميع المراحل بناءً على نفس تعريف النجاح.
بدلاً من البدء بجملة واحدة وتحديد التفاصيل أثناء كتابة الكود، يحوّل Coroid الطلب إلى نطاق عمل محدد، واستثناءات، ومعايير قبول. تصبح تلك الوثيقة المصدر الموثوق به للخطة والتنفيذ والاختبارات والمراجعة النهائية.
ما هو تطوير يعتمد على المواصفات؟
تطوير يعتمد على المواصفات هو أسلوب لبناء البرمجيات استنادًا إلى وصف متفق عليه وقابل للاختبار للنتيجة النهائية. تحدد المواصفة ما الذي سيتغير، وما الذي لن يتغير، والقيود المطبقة، وكيف يمكن للمراجع التأكد من نجاح العمل.
هو يفصل بين قرارين يسهل خلطهما معًا:
- المواصفة المواصفة تحدد معنى النجاح.
- الـ خطة التنفيذ تحدد كيفية تحقيق ذلك.
تتيح لك هذه الفصلية تصحيح نطاق العمل قبل كتابة أي كود، دون فرض خطة تنفيذ مبكرة. في Coroid، يمكنك أيضًا تفعيل سير العمل الاختياري سير عمل دورة حياة تطوير البرمجيات عندما ترغب في الموافقة على النية والمواصفات قبل بدء التخطيط.
كيف يعمل سير العمل في Coroid
- صف النتيجة المرجوة. زود Coroid بالنتيجة التي تحتاجها، والسياق ذي الصلة، وأي قيود أو أهداف غير مرغوب فيها.
- قم بمراجعة المواصفات. تحقق من النطاق والاستثناءات ومعايير القبول في تبويب المهمة المواصفات تبويب.
- اعتمد الخطة. يحول المعماري النتيجة المتفق عليها إلى خطوات تنفيذية مرتبة.
- بناء والتحقق. يستخدم وكلاء المطور وضمان الجودة نفس المعايير لتنفيذ التغيير وإثبات كل سلوك متوقع.
- راجع pull request. تحمل التغييرات المنجزة الخطة ونتائج الاختبارات والنتائج والأدلة وتعيدها إلى المواصفات الأصلية.
النتيجة هي قابلية التتبع من نية المنتج إلى الكود والأدلة التي يراها المراجع البشري. اطلع على كيف تتحول مهمة إلى pull request لمعرفة مسار التنفيذ الكامل.
لماذا هذه الخطوة الإضافية؟
توجيه مثل "إضافة تخزين مؤقت لعمليات بحث المستخدم" له أربع طرق تنفيذ معقولة على الأقل ولا يوجد تعريف للإنجاز. سيختار الوكيل واحدة منها، وما إذا كانت هي الخيار الذي تفضله فهو مسألة حظ.
تجعل المواصفات هذا الاختيار واضحًا قبل بدء التنفيذ، في اللحظة التي يكون فيها تغيير رأيك أقل تكلفة.
كما أنها توفر للتحقق شيئًا للاختبار ضده. بدون معايير قبول، يتحول سؤال "هل عمل ذلك؟" إلى "هل لا تزال الاختبارات تمر؟"، وهو سؤال أضعف بكثير.
ما الذي تحتويه المواصفات؟
| جزء | ما الذي تجيب عليه؟ |
|---|---|
| النطاق | ما الذي سيتغير؟ |
| خارج نطاق العمل | ما لن يتم تنفيذه عمدًا، لمنع اتساع نطاق التغيير |
| معايير القبول | كيف يمكن لأي شخص التأكد من أن التغيير نجح؟ |
| السياق | القيود والاتفاقيات والقرارات السابقة المطبقة |
يمكنك قراءته وتحريره في تبويب المهمة الخاص بـ مواصفات قبل بدء التنفيذ. للاطلاع على وصف العمل والسياق الداعم لهذه العملية، راجع وصف ما تحتاجه.
مثال تطبيقي: من الملخص الأولي إلى مواصفات قابلة للاختبار
لنفترض أن الملخص الأولي هو:
Add caching to the user lookup so repeated requests are faster.هذا يحدد النتيجة المرغوبة، لكنه يترك خيارات مهمة غير محلولة. المواصفات المفيدة تحول هذه الخيارات إلى حدود ومعايير تحقق:
Scope
- Cache successful user lookups by user id for 60 seconds.
- Invalidate the cached entry when the user record is updated.
Out of scope
- Do not cache failed lookups.
- Do not change the public signature of getUser.
Acceptance criteria
- Two lookups for the same user id within 60 seconds call the data source once.
- Updating that user invalidates the existing cache entry.
- A cache miss preserves the current result and error behavior.يمكن للخطة الآن اختيار طريقة التنفيذ، ويمكن لفريق ضمان الجودة تحويل المعايير إلى اختبارات، ويمكن للمراجع مقارنة pull request مع السلوك المتفق عليه.
ما الذي يجعل معايير القبول جيدة؟
يجب أن يكون من الممكن التحقق منها من قبل شخص لم يشارك في الحوار.
ضعيفة:
Caching works correctly and performance is improved.قوية:
- Repeated lookups for the same user id within 60s hit the cache, verified
by a test asserting the data source is called once across two lookups.
- Cache entries are invalidated when the user record is updated.
- A cache miss behaves identically to today, including error handling.
- No change to the public signature of `getUser`.النسخة الثانية تخبر وكيل المطور بما يجب بناؤه، ووكيل ضمان الجودة بما يجب اختباره، وتمكنك من التحقق من pull request. بينما تترك النسخة الأولى كل هذه القرارات مفتوحة.
تحديد نطاق العمل مهم بنفس قدر أهمية المعايير
أكثر الأسباب شيوعًا لتوسع حجم pull request ليس بسبب تجاوز الوكيل للملخص المحدد له، بل بسبب مواصفات لم توضح أين ينتهي ذلك الملخص.
إذا كنت لا تريد إعادة هيكلة الوحدة المحيطة أثناء تنفيذ العمل، فاذكر ذلك. عبارة «عدم تغيير نقاط الاستدعاء» تعتبر شرطًا مفيدًا وضروريًا.
أخطاء شائعة في المواصفات
| خطأ | النهج الأفضل |
|---|---|
| وصف طريقة التنفيذ بدلاً من النتيجة المرغوبة | حدد السلوك والقيود، ثم دع الخطة تختار طريقة التنفيذ المناسبة. |
| استخدام كلمات مثل «سريع» أو «آمن» أو «يعمل بشكل صحيح» | استبدلها بعتبة قابلة للملاحظة أو سلوك محدد أو اختبار. |
| إغفال الأهداف غير المرغوبة | اذكر أسماء الكود أو الواجهات أو السلوكيات التي يجب أن تظل دون تغيير. |
| دمج نتائج غير ذات صلة | قسّم العمل بحيث تنتهي مهمة واحدة بـ pull request قابل للمراجعة. |
| نسخ تذكرة دون التحقق من الافتراضات | أضف السياق والقرارات التي لا يمكن للمستودع البرمجي الكشف عنها. |
عندما تختلف مع المواصفات
قم بتحريرها. المواصفات وثيقة قابلة للتعديل حتى يبدأ التنفيذ، وتصحيحها أقل تكلفة بكثير من تصحيح الكود الناتج عنها.
إذا أظهرت المواصفات أن العمل يتكون من جزأين، فقسّمه إلى مهمتين. يجب أن تنتهي كل مهمة بـ pull request يمكن لشخص واحد مراجعته في جلسة واحدة.
إلى أين ستتجه بعد ذلك
بالنسبة لأي تغيير يتجاوز التغييرات الصغيرة، تصبح المواصفة خطة عمل. اطلع على المهام والخطط ودورات العمل والمسارات، وهو ما يوضح كيفية تقسيم العمل والموافقة عليه قبل كتابة الكود.
أسئلة شائعة
هل المواصفة نفسها التصميم الفني؟
لا. تحدد المواصفة النتيجة المطلوبة والحدود المرتبطة بها. أما التصميم الفني أو خطة التنفيذ فهي توضح البنية التحتية والخطوات اللازمة لتحقيق تلك النتيجة.
هل يحتاج كل تغيير إلى مواصفة مفصلة؟
لا. قد تحتاج التغييرات الصغيرة وغير الغامضة إلى بضعة أسطر توضح النطاق ومعايير القبول فقط. يجب أن تزيل المواصفة أي غموض جوهري، دون إضافة إجراءات معقدة غير ضرورية.
من يجب أن يوافق على المواصفة؟
يجب على الشخص المسؤول عن تحقيق النتيجة التأكد من أن النطاق ومعايير القبول تتوافق مع احتياجات الفريق. ويمكن للموافقين من الجوانب التقنية أو الأمنية أو الامتثال المشاركة عندما تؤثر قيودهم على نجاح المشروع.
هل يمكن تغيير المواصفة بعد بدء العمل؟
يمكن ذلك، لكن يجب أن ينتج عن التغيير إصدار جديد ويستدعي مراجعة الخطة والعمل المرتبطين به. فالتغييرات الصامتة في النطاق تقطع سلسلة الأدلة بين الطلب ونتائج pull request التي تم تسليمها.