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:

PEP 484 standardına uygun tip açıklamaları isteğe bağlı olmakla birlikte, özellikle herkese açık API arayüzlerinde kullanılması şiddetle tavsiye edilmektedir.

Aşağıda, uygun tür ipuçları ve bir Sphinx docstring içeren standart bir işlev tanımına örnek verilmiştir:

def function_name(param1: int, param2: str) -> bool:
"""Türleri ve bir docstring içeren örnek işlev.

:param param1: İlk parametre.
:param param2: İkinci parametre.

:returns: Dönüş değeri. Başarılı olursa True, aksi takdirde False.
"""

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(
    (
 "bu, iki satıra yayılmış
 "çok uzun bir dize"
    ),
    second_argument,
)

yukarıda:

my_function(
    "Bu, iki satıra yayılmış çok uzun bir dize",
    "ikinci_argüman,
)

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.

Yorum yazarken, "biz" gibi birinci çoğul şahıs zamirlerini kullanmaktan kaçının (örneğin, "Biz döngü yapıyoruz" yerine "Döngü yap" yazın).

Test açıklamalarında, her bir testin sergilediği beklenen davranışı belirtin. "Şunu test eder" veya "Şunu sağlar" gibi giriş cümlelerini eklemeyin.

Belgelerde veya yorumlarda kolayca açıklanamayan ek ayrıntılar içeren, daha az bilinen sorunlar için bilet referanslarını saklayın. Bilet numarasını şu şekilde cümlenin sonuna ekleyin:

def test_foo():
 """Bir test docstring'i şöyle görünür (#123456)."""