التسمية والتعليقات والأسلوب القابل للتوسّع

تُقرأ ملفات Playbook مرات أكثر بكثير مما تُكتب. وتحول التسمية والأسلوب المتسقان النص البرمجي الشخصي إلى أتمتة جاهزة للعمل الجماعي. ✨

امنحوا كل مهمة اسمًا واضحًا. تجعل المهام المسماة مخرجات التشغيل سهلة القراءة، وتوضح الغرض منها لزملائكم فورًا.

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

استخدموا module حقيقية بدلًا من shell أو command module. فالوحدات تحقق idempotence وتوثّق نفسها، أما الأوامر المباشرة فلا تفعل ذلك.

اكتبوا معاملات الوحدة بأسلوب YAML block style الواضح، بمفتاح واحد في كل سطر، بدلًا من حشر كل شيء في سلسلة inline واحدة.

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

سمّوا المتغيرات باستخدام lower snake_case، وأضيفوا اسم الدور إلى بداية متغيراته لتجنب التعارض، مثل nginx_port.

ضعوا علامات اقتباس حول أي قيمة تبدأ بـ {{ أو قد تُقرأ كرقم أو قيمة منطقية، حتى لا يخمّن YAML نوعها بشكل خاطئ.

التزموا بمسافتين لكل مستوى، ولا تستخدموا علامات الجدولة مطلقًا. إذ إن YAML حساس للمسافات البيضاء، ولذلك يؤدي خلط المسافات البادئة إلى فشل التحليل.

شغّلوا ansible-lint لاكتشاف مشكلات الأسلوب وأفضل الممارسات تلقائيًا. دعوا الأداة تراجع الالتزام بالمعايير، حتى تركز المراجعات على المنطق.

احرصوا على أن يؤدي كل ملف مهمة واحدة. فملف المهام القصير والواضح الاسم أسهل في الاختبار وإعادة الاستخدام والفهم من ملف متشعب وكبير. 🎯

ما السبب الرئيسي لإضافة name إلى كل مهمة؟

تعلّمتم تسمية كل مهمة، وتفضيل الوحدات على shell، وكتابة YAML واضح، والتعليق على السبب، وترك ansible-lint يفرض الأسلوب. ✅