Ikuti panduan gaya Google TypeScript.
Migrasi ke TypeScript & ES6
Blockly awalnya ditulis dalam ES5.1 sesuai dengan panduan gaya JavaScript
Google JavaScript versi lama yang saat ini digunakan. Kode yang baru ditulis harus mematuhi panduan gaya saat ini dan menggunakan fitur bahasa ES6 seperti let
, const
, class
, dan mendestrukturisasi tugas jika berlaku.
Kode yang ada mungkin akan diperbarui atau mungkin tidak mematuhi persyaratan. Tim Blockly mencoba membuat keputusan terbaik dengan mempertimbangkan konsistensi kode dan pengalaman bagi pengguna library - misalnya, kami dapat memilih untuk tidak mengganti nama fungsi publik yang tidak lagi mematuhi panduan gaya.
Anjuran
- Menggunakan alat analisis lint dan pemformatan.
- Kita menggunakan eslint dan menyiapkan file
.eslintrc.js
dengan aturan untuk gaya pilihan. - Kami menggunakan lebih cantik untuk pemformatan otomatis.
- Jalankan
npm run lint
untuk menjalankan linter dannpm run format
untuk menjalankan pemformat.
- Kita menggunakan eslint dan menyiapkan file
- Indentasi dengan spasi, bukan tab.
- Gunakan titik koma.
- Gunakan
camelCase
untuk variabel dan fungsi. - Gunakan
TitleCase
untuk class. - Gunakan
ALL_CAPS
sebagai konstanta. - Gunakan tanda kurung kurawal
untuk semua struktur kontrol.
- Pengecualian: Anda dapat menghilangkan tanda kurung kurawal untuk pernyataan
if
baris tunggal.
- Pengecualian: Anda dapat menghilangkan tanda kurung kurawal untuk pernyataan
- Gunakan tanda kutip tunggal (kecuali saat menulis JSON).
- Deklarasikan ulang variabel dalam loop
for
. Artinya, selalu tulisfor (const i = 0; ...)
, bukanfor (i = 0; ...)
.- Jika tidak, akan meningkatkan risiko bahwa setelah pemfaktoran ulang lebih tinggi dalam fungsi, variabel akan menjadi usang dan menjadi kejutan global.
- Mulai komentar dengan huruf besar dan akhiri dengan titik.
- Buat masalah GitHub dengan TODO dan tautkan menggunakan
TODO(#issueNumber)
. - Anotasikan semuanya dengan TSDoc.
Larangan
- Indentasi dengan tab.
- Gunakan garis bawah di akhir nama variabel atau fungsi.
- Beberapa kode sebelumnya menggunakan garis bawah untuk properti atau fungsi pribadi atau internal. Meskipun kode tersebut mungkin akan terus ada, tidak ada kode baru yang harus ditambahkan sesuai dengan konvensi ini.
- Gunakan
snake_case
. - Gunakan tanda kutip ganda (kecuali saat menulis JSON).
- Menggunakan TSDoc dengan format yang salah.
- TSDoc kami otomatis dipublikasikan sebagai bagian dari dokumentasi kami.
- Tulis
TODO (username)
.- Sebagai gantinya, buat masalah GitHub dengan TODO dan tautkan menggunakan
TODO(#issueNumber)
.
- Sebagai gantinya, buat masalah GitHub dengan TODO dan tautkan menggunakan
- Gunakan
string.startsWith
. Sebagai gantinya, gunakanBlockly.utils.string.startsWith
.
TSDokumen
Tim Blockly menggunakan TSDoc untuk menganotasi kode kami dan membuat dokumentasi. Kita mengharapkan TSDoc untuk semua properti publik class, dan untuk semua fungsi yang diekspor.
Komentar TSDoc harus diawali dengan /**
dan diakhiri dengan */
agar dapat diurai dengan benar.
Jenis
Jenis dihilangkan dari TSDoc karena informasi tersebut ada dalam kode TypeScript secara langsung. Jika Anda mengedit salah satu dari beberapa file JavaScript yang tersisa, sertakan anotasi jenis sesuai dokumentasi Closure Compiler.
Visibilitas
Fungsi atau properti yang hanya boleh diakses dalam library Blockly harus dianotasi dengan @internal
. Hal ini mencegah properti ini muncul dalam dokumentasi publik. Pengubah visibilitas lainnya harus ditempatkan dalam kode TypeScript secara langsung, bukan di TSDoc.
Properti
TSDoc untuk properti harus menyertakan deskripsi properti. Deskripsi dapat dihilangkan agar mudah dipahami.
/**
* 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);
Fungsi
Anotasi untuk fungsi harus menyertakan
- Deskripsi fungsi
- Satu tag
@param
per parameter, termasuk- Nama
- Deskripsi
- Tag
@returns
jika fungsi tersebut akan menampilkan nilai, beserta deskripsi nilai yang ditampilkan.
Deskripsi dapat dihilangkan untuk fungsi, parameter, atau nilai yang ditampilkan jika dapat dipahami dengan jelas.
Contoh:
/**
* 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;
}