Panduan Gaya Blockly

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 itu berlaku. Baru ditulis kode harus mematuhi panduan gaya saat ini dan menggunakan fitur bahasa ES6 seperti let, const, class, destrukturisasi penetapan jika berlaku. Kode yang ada mungkin 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

  • Gunakan alat pemformatan dan linting.
    • Kami menggunakan eslint dan memiliki .eslintrc.js siapkan file dengan aturan untuk gaya yang kita pilih.
    • Kami menggunakan prettier untuk pemformatan otomatis.
    • Jalankan npm run lint untuk menjalankan linter dan npm run format untuk menjalankan pemformat.
  • 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 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 dilakukan, akan meningkatkan risiko bahwa setelah pemfaktoran ulang berada di posisi yang lebih tinggi variabel tersebut akan menjadi usang dan menjadi kejutan global.
  • 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 hal-hal tersebut masih ada, seharusnya tidak ada kode baru ditambahkan setelah 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. Visibilitas lainnya pengubah harus ditempatkan di kode TypeScript secara langsung, 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;
}