Folgen Sie dem Styleguide für Google TypeScript.
Migration zu TypeScript und ES6
Blockly wurde ursprünglich in ES5.1 gemäß einer älteren, zu diesem Zeitpunkt aktuellen Version des Google JavaScript-Styleguides geschrieben. Neu geschriebener Code sollte dem aktuellen Styleguide entsprechen und ES6-Sprachfunktionen wie let
, const
, class
und gegebenenfalls eine destruktive Zuweisung verwenden.
Vorhandener Code wird möglicherweise aktualisiert oder nicht mehr konform. Das Blockly-Team versucht, die beste Entscheidung unter Berücksichtigung der Codekonsistenz und der Erfahrung für Nutzer der Bibliothek zu treffen. Beispielsweise können wir uns gegen die Umbenennung öffentlicher Funktionen entscheiden, die nicht mehr dem Styleguide entsprechen.
Das sollten Sie tun:
- Verwenden Sie Lint- und Formatierungstools.
- Wir verwenden eslint und haben eine
.eslintrc.js
-Datei mit Regeln für unseren bevorzugten Stil eingerichtet. - Für die automatische Formatierung verwenden wir schöner.
- Führen Sie
npm run lint
aus, um den Linter auszuführen, undnpm run format
, um den Formatierer auszuführen.
- Wir verwenden eslint und haben eine
- Einzug mit Leerzeichen, nicht mit Tabulatorzeichen
- Verwenden Sie Semikolons.
- Verwenden Sie
camelCase
für Variablen und Funktionen. TitleCase
für Kurse verwenden.- Verwenden Sie
ALL_CAPS
für Konstanten. - Verwenden Sie geschweifte Klammern für alle Steuerelementstrukturen.
- Ausnahme: Bei einzeiligen
if
-Anweisungen können Sie die Klammern weglassen.
- Ausnahme: Bei einzeiligen
- Verwenden Sie einfache Anführungszeichen (außer beim Schreiben von JSON).
- Geben Sie Variablen in
for
-Schleifen noch einmal an. Schreiben Sie also immerfor (const i = 0; ...)
anstelle vonfor (i = 0; ...)
.- Andernfalls besteht das Risiko, dass die Variable nach einer Refaktorierung weiter oben in der Funktion verwaist und global zu einer Überraschung wird.
- Kommentare müssen mit Großbuchstaben beginnen und mit Punkten enden.
- Erstellen Sie GitHub-Probleme mit TODOs und verknüpfen Sie sie mit
TODO(#issueNumber)
. - Versehen Sie alles mit TSDoc.
Don'ts
- Einzug mit Tabulatoren
- Verwenden Sie Unterstriche am Ende von Variablen- oder Funktionsnamen.
- In einigen älteren Codes werden Unterstriche für private oder interne Attribute oder Funktionen verwendet. Auch wenn diese möglicherweise weiterhin vorhanden sind, sollte kein neuer Code gemäß dieser Konvention hinzugefügt werden.
snake_case
verwenden.- Verwenden Sie doppelte Anführungszeichen (außer beim Schreiben von JSON).
- Verwende fehlerhaftes TSDoc.
- Unser TSDoc wird automatisch als Teil unserer Dokumentation veröffentlicht.
- Schreiben Sie
TODO (username)
.- Erstellen Sie stattdessen GitHub-Probleme mit TODOs und verknüpfen Sie sie mit
TODO(#issueNumber)
.
- Erstellen Sie stattdessen GitHub-Probleme mit TODOs und verknüpfen Sie sie mit
string.startsWith
verwenden. Verwenden Sie stattdessenBlockly.utils.string.startsWith
.
TSDoc
Das Blockly-Team verwendet TSDoc, um unseren Code zu annotieren und eine Dokumentation zu generieren. Wir erwarten TSDoc für alle öffentlichen Attribute von Klassen und für alle exportierten Funktionen.
TSDoc-Kommentare müssen mit /**
beginnen und mit */
enden, um richtig geparst zu werden.
Typen
Typen werden in TSDoc weggelassen, da sich diese Informationen direkt im TypeScript-Code befinden. Wenn Sie eine der wenigen verbleibenden JavaScript-Dateien bearbeiten, fügen Sie Typanmerkungen gemäß der Dokumentation zu Closure Compiler ein.
Sichtbarkeit
Funktionen oder Attribute, auf die nur innerhalb der Blockly-Bibliothek zugegriffen werden soll, sollten mit @internal
annotiert werden. Dadurch wird verhindert, dass diese Attribute in der öffentlichen Dokumentation aufgeführt werden. Andere Sichtbarkeitsmodifikatoren sollten direkt im TypeScript-Code und nicht im TSDoc platziert werden.
Attribute
Das TSDoc für Eigenschaften sollte eine Beschreibung der Eigenschaft enthalten. Die Beschreibung kann bei selbsterklärenden Eigenschaften weggelassen werden.
/**
* 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);
Funktionen
Annotationen für Funktionen sollten Folgendes enthalten:
- Eine Beschreibung der Funktion
- Ein
@param
-Tag pro Parameter, einschließlich- Name
- Beschreibung
- Ein
@returns
-Tag, wenn die Funktion einen Wert zurückgibt, mit einer Beschreibung des zurückgegebenen Werts
Beschreibungen für Funktionen, Parameter oder Rückgabewerte können weggelassen werden, wenn sie selbsterklärend sind.
Beispiel:
/**
* 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;
}