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 isenpm run format
komutunu çalıştırın.
- Eslint kullanırız ve tercih ettiğimiz stil için kurallar içeren bir
- 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.
- İstisna: Tek satırlık
- Tek tırnak işareti kullanın (JSON yazarken hariç).
- Değişkenleri
for
döngülerinde yeniden bildirin. Yanifor (i = 0; ...)
yerine her zamanfor (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.
- Bunun yerine, Yapılacaklar ile GitHub sorunları oluşturun ve
string.startsWith
hesabını kullan. Bunun yerineBlockly.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;
}