Blok Stil Kılavuzu

Google TypeScript stilini takip edin rehberini inceleyin.

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 işlemlerini kullanmalıdır. Mevcut kod güncellenebilir veya uyumluluğu ihlal edebilir. Blockly ekibi en iyi kararı vermeye çalışırken kod tutarlılığını ve daha iyi bir deneyim sunabiliriz. Örneğin, yeni bir ad kullanmamayı tercih edebiliriz artık stil kılavuzuna uygun olmayan genel işlevler.

Yapılması gerekenler

  • Hata analizi yapma ve biçimlendirme araçlarını kullanın.
    • eslint'i kullanırız ve tercih ettiğimiz stil için kurallar içeren bir .eslintrc.jsdosyası oluştururuz.
    • 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.
  • Sabit değerler için ALL_CAPS kullanın.
  • Kaşlı ayraçları kullanma sahip olması gerekir.
    • İ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ımla. 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.
  • Yapılacaklar ile ilgili GitHub sorunları oluşturun ve bunları TODO(#issueNumber) kullanarak bağlayın.
  • Her şeye TSDoc ile not ekleyin.

Yapılmaması gerekenler:

  • Sekmelerle girintileyin.
  • Değişken veya işlev adlarının sonunda altı çizili kullanın.
    • Önceki bazı kodlar özel veya dahili mülkler için alt çizgi kullanır ya da işlevlerine dahildir. Bunlar var olmaya devam etse de yeni hiçbir kod eklenir.
  • snake_case hesabını kullan.
  • Çift tırnak kullanın (JSON yazarken hariç).
  • Bozuk TSDoc'u kullanın.
    • TSDoc'umuz, dokümanlarımız kapsamında otomatik olarak yayınlanır.
  • TODO (username) yazın.
    • Bunun yerine Yapılacaklar ile GitHub sorunları oluşturun ve bunları TODO(#issueNumber)
  • string.startsWith hesabını kullan. Bunun yerine Blockly.utils.string.startsWith politikasını kullanın.

TSDoc

Blockly ekibi, TSDoc'u kullanarak kodumuza ek açıklama ekler ve belge oluşturmak. Sınıfların tüm herkese açık mülkleri için TSDoc'un kullanılması beklenir. ve dışa aktarılan tüm işlevler için geçerlidir.

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

Türler

Türler, TypeScript kodunda bulunduğu için TSDoc'ta atlanır. ekleyebilirsiniz. Kalan birkaç JavaScript dosyasından birini düzenliyorsanız Kapatma Derleyicisi'ne göre ek açıklamalar yazın ve açıklama dokümanlarına göz atın.

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 işlem, söz konusu mülklerin kamuoyuna yayınlanan belgelerde yer almasıdır. Diğer görünürlük değiştiriciler TSDoc'a değil, doğrudan TypeScript koduna yerleştirilmelidir.

Özellikler

Mülkler için TSDoc'ta, tesisin bir açıklaması yer almalıdır. İlgili içeriği oluşturmak için kullanılan açıklamaya yer vermeyen özellikler için çıkarılabilir.

/**
  *   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

İşlev ek açıklamaları şunları içermelidir:

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

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;
}