Stil kılavuzu

Google TypeScript stil kılavuzuna uyun.

TypeScript ve ES6'ya geçiş

Blockly, başlangıçta Google JavaScript stil kılavuzunun eski ve o zamanki geçerli sürümüne uygun olarak ES5.1'de yazılmıştır. Yeni yazılan kod, geçerli stil kılavuzuna uygun olmalı ve geçerli olduğunda let, const, class gibi ES6 dil özelliklerini ve yapı bozma atama özelliğini kullanmalıdır. Mevcut kod güncellenebilir veya uyumluluğu ihlal edebilir. Blockly ekibi, kod tutarlılığını ve kitaplık kullanıcılarının deneyimini göz önünde bulundurarak en iyi kararı vermeye çalışır. Örneğin, artık stil kılavuzuna uygun olmayan herkese açık işlevleri yeniden adlandırmamayı tercih edebiliriz.

Yapılması gerekenler

  • Hata ayıklama ve biçimlendirme araçlarını kullanın.
    • eslint kullanıyoruz ve tercih ettiğimiz stil için kurallar içeren bir eslint.config.mjs dosyamız var.
    • Otomatik biçimlendirme için prettier'ı kullanırız.
    • Lint aracını çalıştırmak için npm run lint, biçimlendiriciyi çalıştırmak için npm run format'ü çalıştırın.
  • Sekme yerine boşluklarla girinti yapın.
  • Noktalı virgül kullanın.
  • Değişkenler ve işlevler için camelCase kullanın.
  • Sınıflar için TitleCase kullanın.
  • Sabitler için ALL_CAPS kullanın.
  • Tüm kontrol yapıları için parantez kullanın.
    • İstisna: Tek satırlık if ifadeleri için parantezleri atlayabilirsiniz.
  • Tek tırnak işareti kullanın (JSON yazarken hariç).
  • for döngülerinde değişkenleri yeniden tanımlayın. Yani, for (i = 0; ...) yerine her zaman for (const i = 0; ...) yazın.
    • Aksi takdirde, işlevin üst kısmında bir yeniden düzenleme yapıldıktan sonra değişkenin ebeveyni olmadan kalarak beklenmedik bir şekilde global hale gelme riski artar.
  • Yorumları büyük harfle başlatın ve noktayla bitirin.
  • TODO'lar içeren GitHub sorunları oluşturun ve bunları TODO(#issueNumber) kullanarak bağlayın.
  • Her şeye TSDoc ile not ekleyin.

Yapılmaması gerekenler

  • Sekmelerle girinti oluşturma.
  • Değişken veya işlev adlarının sonlarında alt çizgi kullanın.
    • Bazı eski kodlarda, özel veya dahili özellikler ya da işlevler için alt çizgiler kullanılır. Bu kodlar var olmaya devam edebilir ancak bu kurala uygun yeni kod eklenmemelidir.
  • snake_case e-posta adresini kullanın.
  • Çift tırnak kullanın (JSON yazarken hariç).
  • Hatalı biçimlendirilmiş TSDoc kullanın.
    • TSDoc'umuz, dokümanlarımız kapsamında otomatik olarak yayınlanır.
  • TODO (username) yazın.
    • Bunun yerine, TODO'lar içeren GitHub sorunları oluşturun ve bunları TODO(#issueNumber) kullanarak bağlayın.
  • string.startsWith e-posta adresini kullanın. Bunun yerine Blockly.utils.string.startsWith'ü kullanın.

TSDoc

Blockly ekibi, kodumuza ek açıklama eklemek ve doküman oluşturmak için TSDoc'u kullanır. Sınıfların tüm herkese açık özellikleri ve dışa aktarılan tüm işlevler için TSDoc'u bekliyoruz.

Doğru şekilde ayrıştırılabilmesi için TSDoc yorumları /** ile başlamalı ve */ ile bitmelidir.

Türler

Bu bilgiler doğrudan TypeScript kodunda bulunduğundan türler TSDoc'tan çıkarılır. Kalan birkaç JavaScript dosyasından birini düzenliyorsanız Closure Compiler dokümanına göre tür ek açıklamaları ekleyin.

Görünürlük

Yalnızca Blockly kitaplığında erişilmesi gereken işlevler veya özellikler @internal ile ek açıklamaya tabi tutulmalıdır. Bu, söz konusu özelliklerin herkese açık dokümanlarda görünmesini engeller. Diğer görünürlük değiştiriciler, TSDoc'a değil doğrudan TypeScript koduna yerleştirilmelidir.

Özellikler

Tesisler için TSDoc, tesisin açıklamasını içermelidir. Açıklaması kendiliğinden anlaşılan mülkler için açıklama atlanabilir.

/**
  *   The location of the top left of this block (in workspace coordinates)
  *   relative to either its parent block, or the workspace origin if it has no
  *   parent.
  *
  *   @internal
  */
relativeCoords = new Coordinate(0, 0);

İşlevler

İşlevlerle ilgili ek açıklamalar şunları içermelidir:

  • İşlevin açıklaması
  • Parametre başına bir @param etiketi (aşağıdakiler dahil)
    • Ad
    • Açıklama
  • İşlev bir değer döndürecekse döndürülen değerin açıklamasını içeren bir @returns etiketi.

Açıklamayı gerektirmeyen işlevler, parametreler veya döndürülen değerler için açıklamalar atlanabilir.

Örneğin:

/**
 *   Find the workspace with the specified ID.
 *
 *   @param id ID of workspace to find.
 *   @returns The sought after workspace or null if not found.
 */
export function getWorkspaceById(id: string): Workspace | null {
  return WorkspaceDB_[id] || null;
}