Guida di stile Blockly

Segui lo stile Google 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

  • Utilizzare strumenti di lint e formattazione.
    • Utilizziamo eslint e abbiamo una .eslintrc.js configurazione 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.
  • Usa ALL_CAPS per le costanti.
  • Utilizzare le parentesi graffe per tutte le strutture di controllo.
    • Eccezione: puoi omettere le parentesi graffe per le istruzioni if a riga singola.
  • Utilizza le virgolette singole (salvo nella scrittura JSON).
  • Dichiara di nuovo le variabili nei cicli for. In altre parole, scrivi sempre for (const i = 0; ...) anziché for (i = 0; ...).
    • In caso contrario aumenta il rischio che, dopo un refactoring più elevato la variabile diventerà orfana e diventerà una sorpresa a livello globale.
  • Inizia i commenti con lettere maiuscole e terminali con punti.
  • Crea problemi su GitHub con le attività da svolgere e collegali utilizzando TODO(#issueNumber).
  • Aggiungi annotazioni a tutto con TSDoc.

Cosa non fare

  • Inserisci rientri con le tabulazioni.
  • Usa sottolineature alla fine dei nomi di variabili o 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.
  • Usa snake_case.
  • Utilizza le virgolette doppie (tranne nella scrittura 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 su GitHub con le attività da svolgere e collegali utilizzando TODO(#issueNumber).
  • Utilizza string.startsWith. Usa invece il criterio 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 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à che appaiono nella documentazione pubblica. Altra visibilità modificatori deve essere inserito 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, tra cui
    • 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;
}