Panduan Gaya Blockly

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 dan npm run format untuk menjalankan pemformat.
  • 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.
  • Gunakan tanda kutip tunggal (kecuali saat menulis JSON).
  • Deklarasikan ulang variabel dalam loop for. Artinya, selalu tulis for (const i = 0; ...), bukan for (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).
  • Gunakan string.startsWith. Sebagai gantinya, gunakan Blockly.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;
}