Panduan gaya

Ikuti panduan gaya TypeScript Google.

Migrasi ke TypeScript & ES6

Blockly awalnya ditulis dalam ES5.1 sesuai dengan panduan gaya JavaScript Google versi lama, yang saat ini berlaku. Kode yang baru ditulis harus mematuhi panduan gaya saat ini dan menggunakan fitur bahasa ES6 seperti let, const, class, penetapan destrukturisasi jika berlaku. Kode yang ada dapat diperbarui atau tidak dipatuhi. 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

  • Gunakan alat pemformatan dan linting.
    • Kita menggunakan eslint dan menyiapkan file eslint.config.mjs dengan aturan untuk gaya yang kita inginkan.
    • Kami menggunakan prettier untuk pemformatan otomatis.
    • Jalankan npm run lint untuk menjalankan lint dan npm run format untuk menjalankan formator.
  • Tambahkan indentasi dengan spasi, bukan tab.
  • Gunakan titik koma.
  • Gunakan camelCase untuk variabel dan fungsi.
  • Gunakan TitleCase untuk class.
  • Gunakan ALL_CAPS untuk konstanta.
  • Gunakan tanda kurung kurawal untuk semua struktur kontrol.
    • Pengecualian: Anda dapat menghilangkan tanda kurung kurawal untuk pernyataan if satu baris.
  • 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 ada risiko bahwa setelah pemfaktoran ulang di bagian atas fungsi, variabel akan menjadi tidak terpakai dan menjadi global mendadak.
  • Mulai komentar dengan huruf kapital 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 internal atau pribadi. Meskipun kode ini mungkin terus ada, tidak ada kode baru yang harus ditambahkan dengan mengikuti konvensi ini.
  • Gunakan snake_case.
  • Gunakan tanda kutip ganda (kecuali saat menulis JSON).
  • Menggunakan TSDoc yang salah format.
    • 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.

TSDoc

Tim Blockly menggunakan TSDoc untuk menganotasi kode dan membuat dokumentasi. Kami mengharapkan TSDoc untuk semua properti publik class, dan untuk semua fungsi yang diekspor.

Komentar TSDoc harus diawali dengan /** dan diakhiri dengan */ agar dapat diuraikan 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 dengan 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 langsung di kode TypeScript, bukan di TSDoc.

Properti

TSDoc untuk properti harus menyertakan deskripsi properti. Deskripsi dapat dihilangkan untuk properti yang dapat dijelaskan sendiri.

/**
  *   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 akan menampilkan nilai, dengan deskripsi nilai yang ditampilkan.

Deskripsi dapat dihilangkan untuk fungsi, parameter, atau nilai yang ditampilkan jika 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;
}