دليل أسلوب الكود

يتضمن هذا الدليل معلومات وإرشادات لكتابة كود لـ BeeWare.

أسلوب الكتابة

تتبع BeeWare PEP 8 في قاعدة الكود الخاصة بنا، باستثناء طول السطر الذي تم تمديده من 79 إلى 88 حرفًا. نستخدم Ruff لفرض اتفاقيات PEP 8 حيثما أمكن ذلك. عند الالتزام برمزك، سيقوم pre-commit بإجراء فحوصات، بما في ذلك Ruff. حيثما أمكن ذلك، سيؤدي هذا إلى تنسيق رمزك تلقائيًا لضمان توافقه مع معايير التنسيق والأسلوب لدينا. يمكنك إعداد بعض بيئات التطوير المتكاملة (IDE) لتشغيل Ruff تلقائيًا عند الحفظ، مما يساعد في هذه العملية.

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

ويمكن ملاحظة أحد مظاهر ذلك في قواعد تسمية العناصر. غالبًا ما تحتاج مكتبات BeeWare إلى التواصل مع لغات برمجة أخرى. وعند إنشاء غلافات (wrappers) للغات أخرى، يُفضل (بل ويُعد ذلك ضروريًا في بعض الحالات) اتباع قواعد التسمية الخاصة باللغة المستهدفة، بدلاً من لغة Python. على سبيل المثال، عند استدعاء كود Java أو الإشارة إليه، يجب أن تتبع الدوال تفضيل Java المتمثل في استخدام mixedCase، بدلاً من تفضيل PEP 8 المتمثل في استخدام snake_case.

نحن نتبع قواعد التهجئة الأمريكية في تسمية واجهات برمجة التطبيقات والمتغيرات وما إلى ذلك.

هناك أيضًا بعض الإضافات الخاصة بـ BeeWare إلى PEP 8:

تقسيم استدعاءات الدوال الطويلة

عندما لا يتسع استدعاء دالة تحتوي على أكثر من وسيطة واحدة في سطر واحد، ضع كل وسيطة في سطر منفصل مع وضع فاصلة في نهاية الويسيطة الأخيرة. يسمح Ruff (بل ويقترح) بتنسيق يضم عدة وسيطات في سطر واحد مع إعادة الأسطر:

my_function(
    arg1, arg2, arg3
)

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

my_function(
    arg1,
    arg2,
    arg3,
)

تقسيم السلاسل الطويلة

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

my_function(
    (
        "this is a very long string "
        "that is wrapped over two lines"
    ),
    second_argument,
)

فوق:

my_function(
    "this is a very long string "
    "that is wrapped over two lines",
    second_argument,
)

الأمور التي يجب تجنبها

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

كقاعدة عامة، نحاول تجنب أو تأجيل أي كود تهيئة مكلف، من أجل تحقيق بدء تشغيل أسرع للتطبيق. على سبيل المثال، يتم "تحميل" الوحدات النمطية في حزمة toga-core بشكل "متأخر" — حيث يتم استيرادها فقط عند الطلب، بدلاً من استيرادها مسبقًا. يؤدي ذلك إلى تسريع بدء التشغيل، ولا يستغرق وقتًا سوى ما يستخدمه التطبيق فعليًا.