DERLEME Stil Kılavuzu

. Sorun bildirin Kaynağı göster Gece · 7,3 · 7,2 · 7,1 · 7,0 · 6,5

BUILD dosya biçimlendirmesi, Go ile aynı yaklaşımı izler. Standartlaştırılmış aracı sayesinde çoğu biçimlendirme sorununu halleder. Derleyici, bir görevi yapılandırarak kaynak kodu standart bir stilde yayar. Dolayısıyla her BUILD dosyası biçimlendirmenin sorun olmamasına neden olur. Bu nedenle, kod yorumları vardır. Ayrıca araçların anlaşılmasını, düzenlenmesini ve BUILD dosyası oluştur.

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 yorum arasında ayrım yapar ekleyebilirsiniz. Bir yorum belirli bir öğeye eklenmemişse şunu kullanın: boş bir satır olur. RACI matrisinde yapılan değişiklikler (örneğin, kuralı silerken yorumu muhafaza etme veya kaldırma).

# 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şvurulmalıdır (.. gibi yukarı referanslar kullanmadan) Oluşturulan dosyalar ":" ön ekini alır belirtmiyorlar. Kaynak dosyalar : öneki olmamalıdır. Kurallara : ön eki eklenmelidir. Örneğin, Örneğin, x.cc bir 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 tek bir kaynak dosya içeriyorsa hedef, genellikle söz konusu kaynaktan türetilmiş bir ada sahip olmalıdır (örneğin, chat.cc için cc_library, chat veya şunun için java_library olarak adlandırılabilir: DirectMessage.java direct_message olarak adlandırılabilir).

Bir paketin adını taşıyan hedefi (aynı ada sahip hedef içeren dizin), dizin adı. Böyle bir hedef yoksa aynı adı oluşturmayın hedefi belirleyebilirsiniz.

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

"Ayrılmış" ifadesini kullanmaktan kaçının hedef isimleri tanımlamasına yardımcı olur. Buna şunlar dâhildir: all, __pkg__ ve __subpackages__, bu adlar özel anlamları üzerinde durabilir ve kullanıldıklarında karışıklığa ve beklenmeyen davranışlara neden olabilir.

Geçerli bir ekip kongresi olmadığında bu kurallar projeyi Google'da yaygın olarak kullanılan öneriler:

  • Genel olarak "snake_case" kullanın.
    • Bir src içeren java_library için bu, farklı bir ad kullanılması anlamına gelir uzantısı olmayan dosya adıyla aynıdır
    • Java *_binary ve *_test kuralları için şunu kullanın: "Üst CamelCase". Bu, hedef adın src öğelerinden biriyle eşleşmesine olanak tanır. Örneğin, java_test değeri, test_class özelliğinin hedefin adından türetilir.
  • Belirli bir hedefin birden çok varyantı varsa belirsizliklerini ortadan kaldırmak (örneğin, :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ındaki çakışmaları önler.
  • Protoyla ilgili hedefler için:
    • proto_library hedef, _proto ile biten adlara sahip olmalıdır
    • Dillere özgü *_proto_library kuralları, temeldekiyle eşleşmelidir protokolü, ancak _proto öğesini aşağıdakiler gibi dile özgü bir son ekle değiştirin:
      • 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, erişim izni verilmeden önce olabildiğince yakın bir şekilde ayarlanmalıdır. ve ters bağımlılıklara göre şekillendirebilirsiniz. __pkg__ ve __subpackages__ öğelerini şu şekilde kullan: uygun olmalıdır.

default_visibility paketini //visibility:public olarak ayarlamaktan kaçının. //visibility:public yalnızca şuradaki hedefler için ayrı ayrı ayarlanmalıdır: projenin herkese açık API'sini ekleyin. Bunlar, sisteme bağımlı olarak tasarlanan kitaplıklar olabilir. tarafından kullanılabilecek harici projeler veya ikili programlar tarafından geliştirmenizi sağlar.

Bağımlılıklar

Bağımlılıklar doğrudan bağımlılıklarla (bağımlılıklar için gerekli). Geçişli bağımlılıkları listelemeyin.

Paket-yerel bağımlılıklar ilk olarak listelenmeli ve belirli bir şekilde atıfta bulunulmalıdır aşağıdakilerle uyumlu: Mevcut paketteki hedeflere referanslar bölümüne bakın (mutlak paket adlarına göre değil).

Bağımlılıkları doğrudan, tek bir liste olarak listelemeyi tercih edin. "Ortak" kavramı birkaç hedefin değişkene olan bağımlılıkları sürdürülebilirliği azaltır, araçların hedefin bağımlılıklarını değiştirmesi imkansızdır ve bağımlılıkları ortadan kaldırmaktır.

Küreler

"Hedef yok" belirtebilirsiniz [] ile birlikte. Hiçbir şeyle eşleşmeyen bir glob kullanmayın: boş listelere kıyasla hataya daha açık ve daha az belirgindir.

Yinelenen

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

Yinelemeli glob'lar, BUILD dosya atlandığı için dosya üzerinde akıl yürütmeyi zorlaştırıyor BUILD dosya içeren alt dizinler.

Yinelemeli glob'lar genellikle başına bir BUILD dosyasına sahip olmaktan daha az verimlidir bir bağımlılık grafiği olduğundan emin olun. Bu sayede, uzaktan önbelleğe alma ve paralellik.

Her dizin için bir BUILD dosyası yazmak ve bağımlılık grafiğini görebilirsiniz.

Yinelemesiz

Yinelenmeyen glob'lar genellikle kabul edilir.

Diğer kurallar

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

  • 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: Hedeflerin bulma ve değiştirme kolaylığı. Ayrıca okunabilirliği de iyileştirir.

  • Ad özelliğinin değeri, düz bir sabit dize olmalıdır ( makrolarında) yer alır. Rasyonalite: Harici araçlar, bir kuralı. 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ği gibi boole'lere dönüştürmeye devam etmektedir ancak bu önerilmez. Gerekçe: flaky = 1, şöyle bir şekilde yanlış anlaşılabilir: "bir kez yeniden çalıştırarak bu hedefin seviyesini düşür". flaky = True açık bir şekilde diyor "bu test güvenilir değildir".

Python ile farklılıklar stil kılavuzu

Her ne kadar Python stil kılavuzu arasında birkaç fark vardır:

  • Kesin bir satır uzunluğu sınırı yoktur. Uzun yorumlar ve uzun dizeler genellikle bölünür 79 sütuna ekleyebilirsiniz, ancak bu zorunlu değildir. Kodda zorunlu kılınmamalıdır. ön inceleme ve ön gönderme komut dosyalarıdır. Mantıksal: Etiketler uzun olabilir ve bunu aşabilir limit. BUILD dosyalarının araçlar tarafından oluşturulması veya düzenlenmesi yaygın bir durumdur. Bu, 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. İnsanın aklında olmayan bir virgül koyarak tamamen farklı bir sonuç elde edebilirsiniz. Bu durum, proje yönetiminde tercih edebilir. Bu tartışmaya da bakın.

  • Kurallardaki anahtar kelime bağımsız değişkenleri için = işaretinin çevresindeki boşluklar kullanın. Gerekçe: 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ıra ekleyin. Alanlar okunabilirliği iyileştirir. Bu kongre yıl sonuna kadar uzun bir süre saklamaya devam eder ve mevcut tüm BUILD dosyalarını değiştirmeniz gerekmez.

  • Varsayılan olarak, dizeler için çift tırnak işareti kullanın. Mantıksal: belirtilenlere benzer, ancak tutarlılık önerir. Bu yüzden yalnızca çift tırnak içeren dizeler kullanılmasına karar verdi. Birçok dilde çift tırnak işareti kullanılır kullanabilirsiniz.

  • İki üst düzey tanım arasında tek bir boş satır kullanın. Gerekçe: BUILD dosyasının yapısı tipik bir Python dosyasına benzer değildir. Yalnızca söz konusu olabilir. Tek bir boş satır kullanırsanız BUILD dosyaları daha kısa olur.