Kod stil kılavuzu

Bu kılavuz, BeeWare için kod yazmaya ilişkin bilgiler ve yönergeler içerir.

Kod stili

BeeWare, kod tabanımızda PEP 8 kurallarını takip eder, ancak satır uzunluğu 79 karakterden 88 karaktere çıkarılmıştır. Mümkün olduğunda PEP 8 kurallarını uygulamak için Ruff kullanıyoruz. Kodunuzu kaydettiğinizde, pre-commit Ruff dahil olmak üzere çeşitli kontroller yapar. Mümkün olduğunda, kodunuzu biçimlendirme ve stil standartlarımıza uygun hale getirmek için otomatik olarak biçimlendirir. Bazı IDE'leri kaydetme sırasında Ruff'ı otomatik olarak çalıştıracak şekilde ayarlayabilirsiniz, bu da sürece yardımcı olabilir.

PEP 8'in en önemli kısmının Bölüm 0: Aptalca Tutarlılık Küçük Zihinlerin Hobgoblinidir olduğunu unutmayın. PEP 8 ile tutarlı kalmanın mantıklı olmadığı durumlar vardır ve uygun olduğunda, listelenen kurallara uymayan kod yazmanın kabul edilebilir ve bazen tercih edilebilir olduğunu anlamak önemlidir. Bu kurallara ne zaman tutarsız olunması gerektiğini bilmek, çoğu durumda tutarlılığı korumak kadar önemlidir.

Bunun bir örneği, adlandırma kurallarında görülebilir. BeeWare kütüphaneleri sıklıkla diğer dillerle entegrasyon kurmak zorundadır. Diğer dillere yönelik sarmalayıcılar oluşturulurken, Python yerine hedef dilin adlandırma kurallarına uymak tercih edilir (ve bazı durumlarda zorunludur). Örneğin, Java kodunu çağırırken veya referans verirken, işlevler PEP 8'in mixedCase tercihini değil, Java'nın snake_case tercihini benimsemelidir.

API adlandırma, değişkenler vb. için ABD yazım kurallarını takip ediyoruz.

PEP 8'e BeeWare'e özgü bazı eklemeler de yapılmıştır:

Uzun işlev çağrılarını bölme

Birden fazla argüman içeren bir işlev çağrısı tek bir satıra sığmadığında, her argümanı ayrı bir satıra yerleştirin ve son argümanın sonuna virgül ekleyin. Ruff, birden fazla argümanın tek bir satıra sığdırılmasına izin verir (ve bunu önerir):

my_function(
    arg1, arg2, arg3
)

Bu biçim kullanılmamalıdır. Bunun yerine, son argümana sondan virgül ekleyerek argümanları her satıra bir tane olacak şekilde dağıtın:

my_function(
    arg1,
    arg2,
    arg3,
)

Uzun dizeleri bölme

Bir dize argümanının satır uzunluğu kısıtlamalarına uymak için satırlara bölünmesi gerektiğinde, birleştirilmiş dize sabitlerini parantez içine alın; böylece dizenin tek bir argüman olduğu açıkça anlaşılır. Yani, şu şekilde yazmayı tercih ederiz:

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

yukarıda:

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

Kaçınılması gerekenler

Bazen kaçınılmaz olduklarını bilerek, utils modüllerini mümkün olduğunca kullanmamaya çalışıyoruz. Tercih edilen alternatif, utils modülünü kullanmak yerine, kaynak kodun başka bir yerinde bu özelliği bulmaktır.

Genel bir kural olarak, uygulamanın daha hızlı başlatılması için pahalı başlatma kodlarını önlemeye veya ertelemeye çalışırız. Örneğin, toga-core paketindeki modüller "tembel yükleme" ile çalışır; yani, önceden değil, yalnızca talep edildiğinde içe aktarılır. Bu, başlatma sürecini hızlandırır ve yalnızca uygulamanın gerçekten kullandığı şeyler için zaman harcanmasını sağlar.