راهنمای سبک کدنویسی

این راهنما شامل اطلاعات و دستورالعمل‌هایی برای نوشتن کد برای BeeWare است.

سبک کد

BeeWare در پایگاه کد خود از PEP 8 پیروی می‌کند، با این تفاوت که طول خط از ۷۹ به ۸۸ کاراکتر افزایش یافته است. ما از Ruff برای اعمال قراردادهای PEP 8 در صورت امکان استفاده می‌کنیم. وقتی کد خود را کامیت می‌کنید، pre-commit بررسی‌ها از جمله Ruff را اجرا می‌کند. در صورت امکان، این ابزار کد شما را به‌طور خودکار قالب‌بندی می‌کند تا مطمئن شویم با استانداردهای قالب‌بندی و سبک ما مطابقت دارد. می‌توانید برخی از محیط‌های توسعه (IDEها) را طوری تنظیم کنید که هنگام ذخیره به‌طور خودکار Ruff را اجرا کنند، که می‌تواند در این فرایند کمک کند.

به خاطر داشته باشید که مهم‌ترین بخش PEP 8 عبارت است از بخش ۰: یکنواختی احمقانه شبح هولناک ذهن‌های کوچک است. موقعیت‌هایی وجود دارد که پایبندی به PEP 8 منطقی نیست و مهم است بدانید که در صورت لزوم، نوشتن کدی که با قوانین ذکرشده هم‌خوانی ندارد، قابل قبول و گاهی ترجیح داده می‌شود. دانستن اینکه چه زمانی باید با آن قوانین ناسازگار بود به همان اندازه حفظ سازگاری در اکثر موقعیت‌ها اهمیت دارد.

یکی از جلوه‌های این موضوع را می‌توان در قراردادهای نام‌گذاری مشاهده کرد. کتابخانه‌های BeeWare اغلب نیاز دارند تا به زبان‌های دیگر پل بزنند. هنگام ساختن روکش‌های رابط (wrapper) برای زبان‌های دیگر، مطلوب است (و در برخی موارد ضروری) که به جای پایتون، از قراردادهای نام‌گذاری زبان مقصد پیروی شود. برای مثال، هنگام فراخوانی یا ارجاع به کد جاوا، توابع باید ترجیح جاوا برای استفاده از mixedCase را دنبال کنند، نه ترجیح PEP 8 برای استفاده از snake_case.

ما برای نام‌گذاری API، متغیرها و غیره از املای آمریکایی پیروی می‌کنیم.

همچنین چند افزودهٔ خاص 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 به‌صورت تنبلانه بارگذاری می‌شوند — آن‌ها تنها زمانی وارد می‌شوند که درخواست شوند، نه همه در ابتدا. این کار راه‌اندازی را تسریع می‌کند و تنها زمانی صرف آنچه برنامه واقعاً استفاده می‌کند، می‌شود.