DERLEME Stil Kılavuzu

Sorun bildirin Kaynağı göster

BUILD dosya biçimlendirmesi, çoğu biçimlendirme sorununun standart bir araç tarafından ele alındığı Go ile aynı yaklaşımı uygular. Buildifier, kaynak kodunu standart bir stilde ayrıştırıp yayan bir araçtır. Bu nedenle, her BUILD dosyası aynı otomatik şekilde biçimlendirilir. Böylece, kod incelemeleri sırasında biçimlendirmenin bir sorun olmaması sağlanır. Ayrıca araçların BUILD dosyalarını anlamasını, düzenlemesini ve oluşturmasını da kolaylaştırır.

BUILD dosya biçimlendirmesi, buildifier çıktısıyla eşleşmelidir.

Biçimlendirme örneği

# Test code implementing the Foo controller.
package(default_testonly = True)

py_test(
    name = "foo_test",
    srcs = glob(["*.py"]),
    data = [
        "//data/production/foo:startfoo",
        "//foo",
        "//third_party/java/jdk:jdk-k8",
    ],
    flaky = True,
    deps = [
        ":check_bar_lib",
        ":foo_data_check",
        ":pick_foo_port",
        "//pyglib",
        "//testing/pybase",
    ],
)

Dosya yapısı

Öneri: Aşağıdaki sırayı kullanın (her öğe isteğe bağlıdır):

  • Paket açıklaması (yorum)

  • load() ekstresinin tümü

  • package() işlevi.

  • Kurallara ve makrolara yapılan çağrılar

Derleyici, bağımsız bir yorum ile bir öğeye ekli yorum arasında ayrım yapar. Bir yorum belirli bir öğeye ekli değilse arkasından boş bir satır kullanın. Bu ayrım, otomatik değişiklikler yaparken (örneğin, bir kuralı silerken yorumu tutmak veya kaldırmak için) önemlidir.

# Standalone comment (such as to make a section in a file)

# Comment for the cc_library below
cc_library(name = "cc")

Geçerli paketteki hedeflere referanslar

Dosyalara, paket dizinine göre kendi yollarıyla başvuruda bulunulmalıdır (.. gibi yukarı referanslar hiç kullanılmadan). Oluşturulan dosyalara kaynak olmadıklarını belirtmek için ":" öneki eklenmelidir. Kaynak dosyalara : ön eki eklenmemelidir. Kurallara : ön eki eklenmelidir. Örneğin, x.cc değerinin kaynak dosya olduğu varsayıldığında:

cc_library(
    name = "lib",
    srcs = ["x.cc"],
    hdrs = [":gen_header"],
)

genrule(
    name = "gen_header",
    srcs = [],
    outs = ["x.h"],
    cmd = "echo 'int x();' > $@",
)

Hedef adlandırma

Hedef adları açıklayıcı olmalıdır. Bir hedef, bir kaynak dosya içeriyorsa hedefin genellikle bu kaynaktan türetilmiş bir adı olmalıdır (örneğin, chat.cc için cc_library, chat veya DirectMessage.java için java_library olarak direct_message adlandırılabilir).

Bir paketin adını taşıyan hedefi (içeren dizinle aynı ada sahip hedef), dizin adında açıklanan işlevi sağlamalıdır. Böyle bir hedef yoksa aynı ada sahip bir hedef oluşturmayın.

Aynı ada sahip bir hedefe atıfta bulunurken kısa adı kullanmayı tercih edin (//x:x yerine //x). Aynı paketteyseniz yerel referansı tercih edin (//x yerine :x).

Özel anlamı olan "ayrılmış" hedef adları kullanmaktan kaçının. Buna all, __pkg__ ve __subpackages__ dahildir. Bu adlar özel anlamlara sahiptir ve kullanıldıklarında karışıklığa ve beklenmeyen davranışlara neden olabilir.

Geçerli bir ekip kuralının olmadığı durumlarda, Google'da yaygın olarak kullanılan ve bağlayıcı olmayan bazı öneriler şunlardır:

  • Genel olarak, "snake_case" kullanın
    • Bir src içeren java_library için bu, uzantı olmadan dosya adıyla aynı olmayan bir ad kullanılması anlamına gelir
    • Java *_binary ve *_test kuralları için "Upper CamelCase" değerini kullanın. Bu, hedef adın src öğelerinden biriyle eşleşmesine olanak tanır. java_test için bu, test_class özelliğinin hedef adından çıkarılabilmesini sağlar.
  • Belirli bir hedefin birden çok varyantı varsa belirsizleştirmek için sonek ekleyin (ör. :foo_dev, :foo_prod veya :bar_x86, :bar_x64)
  • _test son eki, _test, _unittest, Test veya Tests ile hedeflenir
  • _lib veya _library gibi anlamsız son ekler kullanmaktan kaçının (_library hedefi ile karşılık gelen _binary arasında çakışmaları önlemek için gerekli olmadığı sürece)
  • Protoyla ilgili hedefler için:
    • proto_library hedef, _proto ile biten adlara sahip olmalıdır
    • Dillere özgü *_proto_library kuralları, temel alınan protokolle eşleşmeli ancak _proto yerine aşağıdaki gibi bir dile özgü sonek eklemelidir:
      • cc_proto_library: _cc_proto
      • java_proto_library: _java_proto
      • java_lite_proto_library: _java_proto_lite

Görünürlük

Görünürlük kapsamı mümkün olduğunca sıkı bir şekilde ayarlanmalı, aynı zamanda testlerle ve ters bağımlılıklarla erişim sağlanmalıdır. __pkg__ ve __subpackages__ öğelerini uygun şekilde kullanın.

default_visibility paketini //visibility:public olarak ayarlamaktan kaçının. //visibility:public, yalnızca projenin herkese açık API'sindeki hedefler için ayrı ayrı ayarlanmalıdır. Bunlar, harici projelerden yararlanmak üzere tasarlanmış kitaplıklar veya harici bir projenin derleme sürecinde kullanılabilecek ikili programlar olabilir.

Bağımlılıklar

Bağımlılıklar doğrudan bağımlılıklarla (kuralda listelenen kaynakların ihtiyaç duyduğu bağımlılıklar) sınırlandırılmalıdır. Geçişli bağımlılıkları listelemeyin.

Paket-yerel bağımlılıklar, yukarıdaki Mevcut paketteki hedeflere yapılan referanslar bölümünde (mutlak paket adlarıyla değil) uyumlu şekilde listelenmeli ve bunlara atıfta bulunulmalıdır.

Bağımlılıkları doğrudan, tek bir liste olarak listelemeyi tercih edin. Birkaç hedefin "yaygın" bağımlılıklarını bir değişkene yerleştirmek sürdürülebilirliği azaltır, araçların hedef bağımlılıklarını değiştirmesini imkansız kılar ve kullanılmayan bağımlılıklara yol açabilir.

Küreler

[] ile "hedef yok" belirtebilirsiniz. Hiçbir şeyle eşleşmeyen bir glob kullanmayın. Bu, boş bir listeye göre daha hataya açık ve daha az belirgindir.

Yinelenen

Kaynak dosyaları eşleştirmek için yinelemeli glob'ları kullanmayın (örneğin, glob(["**/*.java"])).

Yinelemeli glob'lar, BUILD dosyalarını içeren alt dizinleri atladıkları için BUILD dosyalarını akıl yürütmeyi zorlaştırır.

Yinelemeli glob'lar, daha iyi uzaktan önbelleğe alma ve paralellik sağladığından, aralarında bağımlılık grafiği bulunan bir dizin başına BUILD dosyasına sahip olmaktan genellikle daha az verimlidir.

Her dizin için bir BUILD dosyası yazmak ve bunlar arasında bir bağımlılık grafiği tanımlamak iyi bir uygulamadır.

Yinelemesiz

Yinelenmeyen glob'lar genellikle kabul edilir.

Diğer kurallar

  • Sabit değerleri (ör. GLOBAL_CONSTANT) bildirmek için büyük harf ve alt çizgi, değişkenleri (ör. my_variable) bildirmek için küçük harf ve alt çizgi kullanın.

  • 79 karakterden uzun olsa bile etiketler hiçbir zaman bölünmemelidir. Etiketler, mümkün olduğunda dize değişmez değeri olmalıdır. Mantıksal: Bulma ve değiştirme işlemini kolaylaştırır. Ayrıca okunabilirliği de iyileştirir.

  • Ad özelliğinin değeri, sabit bir sabit dize olmalıdır (makrolar hariç). Rasyonalite: Harici araçlar, bir kuralı belirtmek için ad özelliğini kullanır. Kodu yorumlamak zorunda kalmadan kuralları bulmaları gerekir.

  • Boole türündeki özellikleri ayarlarken tam sayı değerlerini değil, boole değerlerini kullanın. Eski nedenlerden dolayı, kurallar tam sayıları gerektiğinde boole'lere dönüştürmeye devam eder ancak bu önerilmez. Mantıksal: flaky = 1, "bu hedefin tabanını bir kez yeniden çalıştırarak boşaltın" şeklinde yanlış okunabilir. flaky = True açık bir şekilde "bu testte kesintisiz" diyor.

Python ile farklılıklar stil kılavuzu

Python stil kılavuzuyla uyumluluk hedef olsa da bazı farklılıklar vardır:

  • Kesin bir satır uzunluğu sınırı yoktur. Uzun yorumlar ve uzun dizeler genellikle 79 sütuna bölünür ancak bu zorunlu değildir. Kod incelemelerinde veya ön gönderme komut dosyalarında zorunlu kılınmamalıdır. Mantıksal: Etiketler uzun olabilir ve bu sınırı aşabilir. BUILD dosyalarının araçlar tarafından oluşturulması veya düzenlenmesi yaygın bir durumdur. Bu durum, satır uzunluğu sınırlamasına uygun değildir.

  • Örtülü dize birleştirmesi desteklenmez. + operatörünü kullanın. Mantıksal: BUILD dosyaları çok sayıda dize listesi içeriyor. Virgül kolayca unutulabiliyor. Bu da tamamen farklı bir sonuç doğuruyor. Bu durum geçmişte birçok hataya yol açmıştır. Bu tartışmaya da bakın.

  • Kurallardaki anahtar kelime bağımsız değişkenleri için = işaretinin çevresindeki boşluklar kullanın. Mantıksal: Adlandırılmış bağımsız değişkenler Python'da olduğundan çok daha sık kullanılır ve her zaman ayrı bir satırda yer alır. Alanlar okunabilirliği iyileştirir. Bu kural uzun zamandır kullanılıyor ve mevcut tüm BUILD dosyalarını değiştirmenize değmez.

  • Varsayılan olarak, dizeler için çift tırnak işareti kullanın. Rasyonale: Bu, Python stil kılavuzunda belirtilmemiş olsa da tutarlılık önermektedir. Bu yüzden yalnızca çift tırnak içeren dizeler kullanmaya karar verdik. Birçok dil, düz dizeler için çift tırnak işareti kullanır.

  • İki üst düzey tanım arasında tek bir boş satır kullanın. Mantıksal: BUILD dosyasının yapısı, tipik bir Python dosyasına benzer değildir. Yalnızca üst düzey ifadeler vardır. Tek bir boş satır kullanırsanız BUILD dosyaları daha kısa olur.