Guida di stile

Segui la guida di Google allo stile TypeScript.

Migrazione a TypeScript ed ES6

Blockly è stato scritto originariamente in ES5.1 in conformità con una versione precedente della Guida allo stile JavaScript di Google. Il codice appena scritto deve essere conforme alla guida di stile corrente e utilizzare le funzionalità del linguaggio ES6 come let, const, class, l'assegnazione distrutturata, ove applicabile. Il codice esistente potrebbe essere aggiornato o potrebbe non essere conforme. Il team di Blockly cerca di prendere la decisione migliore tenendo conto della coerenza del codice e dell'esperienza degli utenti della libreria. Ad esempio, potremmo scegliere di non rinominare le funzioni pubbliche che non sono più conformi alla guida di stile.

Cosa fare

  • Utilizza gli strumenti di linting e formattazione.
    • Utilizziamo eslint e abbiamo configurato un eslint.config.mjs file con le regole per il nostro stile preferito.
    • Utilizziamo prettier per la formattazione automatica.
    • Esegui npm run lint per eseguire l'linter e npm run format per eseguire il formattatore.
  • Usa gli spazi per rientrare, non le tabulazioni.
  • Utilizza i due punti.
  • Utilizza camelCase per variabili e funzioni.
  • Usa TitleCase per i corsi.
  • Utilizza ALL_CAPS per le costanti.
  • Utilizza le parentesi graffe per tutte le strutture di controllo.
    • Eccezione: puoi omettere le parentesi graffe per le istruzioni if a riga singola.
  • Utilizza virgolette singole (tranne quando scrivi JSON).
  • Dichiara di nuovo le variabili nei cicli for. In altre parole, scrivi sempre for (const i = 0; ...) anziché for (i = 0; ...).
    • Se non lo fai, rischi che dopo un refactoring più in alto nella funzione la variabile venga rimossa e diventi una variabile globale inaspettata.
  • Inizia i commenti con lettere maiuscole e terminali con dei punti.
  • Crea issue di GitHub con elementi da fare e collegali utilizzando TODO(#issueNumber).
  • Aggiungi annotazioni a tutto con TSDoc.

Cosa non fare

  • Inserisci rientri con le tabulazioni.
  • Utilizza i trattini bassi alla fine dei nomi delle variabili o delle funzioni.
    • Alcuni codici precedenti utilizzano gli underscore per proprietà o funzioni private o interne. Sebbene possano continuare a esistere, non deve essere aggiunto nessun nuovo codice in base a questa convenzione.
  • Utilizza snake_case.
  • Utilizza le virgolette doppie (tranne quando scrivi JSON).
  • Utilizzo di un TSDoc con formato non corretto.
    • Il nostro TSDoc viene pubblicato automaticamente nell'ambito della nostra documentazione.
  • Scrivi TODO (username).
    • Crea invece problemi GitHub con elementi TODO e collegali utilizzando TODO(#issueNumber).
  • Utilizza string.startsWith. Utilizza invece Blockly.utils.string.startsWith.

TSDoc

Il team di Blockly utilizza TSDoc per annotare il codice e generare la documentazione. Prevediamo TSDoc per tutte le proprietà pubbliche delle classi e per tutte le funzioni esportate.

I commenti TSDoc devono iniziare con /** e terminare con */ per essere analizzati correttamente.

Tipi

I tipi vengono omessi da TSDoc perché queste informazioni sono contenute direttamente nel codice TypeScript. Se stai modificando uno dei pochi file JavaScript rimanenti, includi le annotazioni del tipo in base alla documentazione di Closure Compiler.

Visibilità

Le funzioni o le proprietà a cui deve essere eseguito l'accesso solo all'interno della libreria Blockly devono essere annotate con @internal. In questo modo, queste proprietà non vengono visualizzate nella documentazione pubblica. Gli altri modificatori della visibilità devono essere inseriti direttamente nel codice TypeScript, non nel TSDoc.

Proprietà

Il file TSDoc per le proprietà deve includere una descrizione della proprietà. La descrizione può essere omessa per le proprietà autoesplicative.

/**
  *   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);

Funzioni

Le annotazioni per le funzioni devono includere

  • Una descrizione della funzione
  • Un tag @param per parametro, incluso
    • Nome
    • Descrizione
  • Un tag @returns se la funzione restituisce un valore, con una descrizione del valore restituito.

Le descrizioni possono essere omesse per funzioni, parametri o valori restituiti se sono autoesplicative.

Ad esempio:

/**
 *   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;
}