Blockly-Styleguide

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, und npm run format, um den Formatierer auszuführen.
  • 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.
  • Verwenden Sie einfache Anführungszeichen (außer beim Schreiben von JSON).
  • Geben Sie Variablen in for-Schleifen noch einmal an. Schreiben Sie also immer for (const i = 0; ...) anstelle von for (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).
  • string.startsWith verwenden. Verwenden Sie stattdessen Blockly.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;
}