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 enpm run format
per eseguire il formatter.
- Utilizziamo eslint e abbiamo configurato un file
- 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.
- Eccezione: puoi omettere le parentesi graffe nelle istruzioni
- Utilizza le virgolette singole (tranne quando scrivi in formato JSON).
- Riqualifica le variabili in
for
loop. Vale a dire, scrivi semprefor (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)
.
- Crea invece problemi su GitHub con TODO e collegali utilizzando
- Usa
string.startsWith
. Usa invece il criterioBlockly.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;
}