Guida di stile Blockly

Segui la guida di stile di Google TypeScript.

Migrazione a TypeScript ed ES6

Blockly è stato originariamente scritto in ES5.1 in conformità a una versione precedente e aggiornata della guida di stile per JavaScript di Google. Il codice appena scritto deve essere conforme alla guida di stile attuale e utilizzare funzionalità del linguaggio ES6 come let, const, class, ove applicabile, in modo da rendere inaccessibili i compiti. Il codice esistente potrebbe essere aggiornato o non essere conforme. Il team di Blockly cerca di prendere la decisione migliore prendendo in considerazione la coerenza del codice e l'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

• Utilizzare strumenti di analisi tramite lint e di formattazione.
  • Utilizziamo eslint e abbiamo configurato un file .eslintrc.js con le regole per il nostro stile preferito.
  • Utilizziamo prettier per la formattazione automatica.
  • Esegui npm run lint per eseguire il linter e npm run format per eseguire il formatter.
• Rientro con spazi, non tabulazioni.
• Utilizza il punto e virgola.
• Utilizza camelCase per variabili e funzioni.
• Usa TitleCase per i corsi.
• Usa ALL_CAPS per le costanti.
• Utilizza parentesi graffe per tutte le strutture di controllo.
  • Eccezione: puoi omettere le parentesi graffe nelle istruzioni if a riga singola.
• Utilizza le virgolette singole (tranne quando scrivi in formato JSON).
• Riqualifica le variabili in for loop. Vale a dire, scrivi sempre for (const i = 0; ...) anziché for (i = 0; ...).
  • In caso contrario, aumenta il rischio che, dopo un refactoring a livello più alto nella funzione, la variabile rimanga orfana e diventi una sorpresa globale.
• Iniziare i commenti con le lettere maiuscole e terminare con dei punti.
• Crea problemi su GitHub con TODO e collegali utilizzando TODO(#issueNumber).
• Aggiungi annotazioni a ogni elemento con TSDoc.

Cosa non fare

• Rientro con tabulazioni.
• Utilizza sottolineature alla fine dei nomi delle variabili o delle funzioni.
  • Alcuni codici precedenti utilizzano trattini bassi per le proprietà o le funzioni private o interne. Anche se potrebbero continuare a esistere, non è necessario aggiungere nuovo codice seguendo questa convenzione.
• Usa snake_case.
• Utilizza le virgolette doppie (tranne quando scrivi in formato JSON).
• Utilizza TSDoc non corretto.
  • Il nostro documento TSDoc viene pubblicato automaticamente come parte della nostra documentazione.
• Scrivi TODO (username).
  • Crea invece problemi su GitHub con TODO e collegali utilizzando TODO(#issueNumber).
• Usa string.startsWith. Usa invece il criterio Blockly.utils.string.startsWith.

Documento di assistenza tecnica

Il team di Blockly utilizza TSDoc per annotare il nostro codice e generare documentazione. Prevediamo che 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é le informazioni si trovano direttamente nel codice TypeScript. Se stai modificando uno dei pochi file JavaScript rimanenti, includi le annotazioni del tipo secondo la documentazione di Closure Compiler.

Visibilità

Le funzioni o le proprietà a cui si deve accedere solo all'interno della libreria Blockly devono essere annotate con @internal. In questo modo, queste proprietà non appariranno nella documentazione pubblica. Altri modificatori di visibilità devono essere inseriti direttamente nel codice TypeScript, non nel documento TSDoc.

Proprietà

Il documento TSDoc relativo alle proprietà deve includere una descrizione. 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 restituirà un valore con una descrizione del valore restituito.

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

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