Blok Stil Kılavuzu

Google TypeScript stil kılavuzunu takip edin.

TypeScript ve ES6'ya taşıma

Blockly ilk başta ES5.1'de Google JavaScript stil kılavuzunun daha eski ve o sırada geçerli olan sürümüne uygun şekilde yazılmıştı. Yeni yazılan kod, mevcut stil kılavuzuna uygun olmalı ve uygun durumlarda let, const, class gibi ES6 dil özelliklerini kullanmalıdır. Mevcut kod güncellenebilir veya kanunlara ve kurallara uygun olmaktan çıkarılabilir. Blockly ekibi, kod tutarlılığını ve kitaplık kullanıcılarının deneyimini dikkate alarak 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ırız ve tercih ettiğimiz stil için kurallar içeren bir .eslintrc.js dosyası oluştururuz.
    • Otomatik biçimlendirme için daha güzel olanı kullanırız.
    • Lint aracını çalıştırmak için npm run lint, biçimlendirmeyi çalıştırmak için ise npm run format komutunu çalıştırın.
  • Sekmelerle değil boşluklarla girintileyin.
  • 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.
  • Tüm kontrol yapıları için kaşlı ayraç kullanın.
    • İstisna: Tek satırlık if ifadeleri için küme ayraçlarını çıkarabilirsiniz.
  • Tek tırnak işareti kullanın (JSON yazarken hariç).
  • Değişkenleri for döngülerinde yeniden bildirin. Yani for (i = 0; ...) yerine her zaman for (const i = 0; ...) yazın.
    • Aksi takdirde, işlevdeki yeniden düzenleme işleminden sonra değişkenin "artık" hale gelmesi ve küresel çapta sürpriz bir hale gelmesi riski artar.
  • Yorumları büyük harfle başlatıp noktayla bitirin.
  • Yapılacaklar ile GitHub sorunları oluşturun ve TODO(#issueNumber) kullanarak bunları bağlayın.
  • TSDoc ile her şeye not ekleyin.

Yapılmaması gerekenler

  • Sekmelerle girintileyin.
  • Değişken veya işlev adlarının sonunda alt çizgi kullanın.
    • Önceki bazı kodlar özel veya dahili mülkler ya da işlevler için alt çizgi kullanır. Bu kod mevcut olsa da bu kurala göre yeni kod eklenmemelidir.
  • snake_case hesabını kullan.
  • Çift tırnak kullanın (JSON yazarken hariç).
  • Bozuk TSDoc kullanın.
    • TSDocmuz, dokümanlarımızın bir parçası olarak otomatik olarak yayınlanmaktadır.
  • TODO (username) yazın.
    • Bunun yerine, Yapılacaklar ile GitHub sorunları oluşturun ve TODO(#issueNumber) kullanarak bunları bağlayın.
  • string.startsWith hesabını kullan. Bunun yerine Blockly.utils.string.startsWith politikasını kullanın.

TSDoc

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

TSDoc yorumlarının doğru ayrıştırılabilmesi için /** ile başlaması ve */ ile bitmesi gerekir.

Türler

Türler, doğrudan TypeScript kodunda olduğundan TSDoc'tan çıkarılır. Kalan az sayıdaki JavaScript dosyasından birini düzenliyorsanız Closure Derleyici belgelerine uygun şekilde tür ek açıklamaları ekleyin.

Görünürlük

Yalnızca Blockly kitaplığından erişilmesi gereken işlevlere veya özelliklere @internal ile not eklenmelidir. Bu, bu mülklerin herkese açık belgelerde görünmesini engeller. Diğer görünürlük değiştiricileri, TSDoc'a değil, doğrudan TypeScript koduna yerleştirilmelidir.

Özellikler

Mülklere ilişkin TSDoc, özelliğin bir açıklamasını içermelidir. Açıklama, açıklayıcı özellikler için 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

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

İşlevler ve parametreler için açıklamalar çıkarılabilir veya kendinden açıklayıcı olmaları halinde değer döndürebilir.

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