Styleguide

Beachten Sie den Google-Leitfaden für TypeScript-Stile.

Migration zu TypeScript und ES6

Blockly wurde ursprünglich in ES5.1 gemäß einer älteren, damals aktuellen Version des Google-JavaScript-Stilhandbuchs geschrieben. Neu geschriebener Code muss dem aktuellen Styleguide entsprechen und ES6-Sprachfunktionen wie let, const, class und ggf. die Destrukturierungszuweisung verwenden. Vorhandener Code kann aktualisiert oder nicht konform bleiben. Das Blockly-Team versucht, die beste Entscheidung unter Berücksichtigung der Codekonsistenz und der Nutzerfreundlichkeit der Bibliothek zu treffen. So entscheiden wir uns beispielsweise möglicherweise, öffentliche Funktionen, die nicht mehr dem Styleguide entsprechen, nicht umzubenennen.

Do

  • Lint- und Formatierungstools verwenden
    • Wir verwenden eslint und haben eine eslint.config.mjs-Datei mit Regeln für unseren bevorzugten Stil eingerichtet.
    • Wir verwenden prettier für die automatische Formatierung.
    • Führen Sie npm run lint aus, um den Linter und npm run format aus, um den Formatierer auszuführen.
  • Verwenden Sie zum Einrücken Leerzeichen, keine Tabulatoren.
  • Verwenden Sie Semikolons.
  • Verwenden Sie camelCase für Variablen und Funktionen.
  • Verwenden Sie TitleCase für Kurse.
  • Verwenden Sie ALL_CAPS für Konstanten.
  • Verwenden Sie für alle Kontrollstrukturen Klammern.
    • Ausnahme: Bei einer einzeiligen if-Anweisung können Sie die geschweiften Klammern weglassen.
  • Verwenden Sie einfache Anführungszeichen (außer beim Schreiben von JSON).
  • Variablen in for-Schleifen neu deklarieren Schreibe also immer for (const i = 0; ...) statt for (i = 0; ...).
    • Andernfalls besteht das Risiko, dass die Variable nach einer Refaktorisierung weiter oben in der Funktion verwaist und zu einer unerwarteten globalen Variablen wird.
  • Kommentare müssen mit Großbuchstaben beginnen und mit einem Punkt enden.
  • Erstellen Sie GitHub-Probleme mit TODOs und verknüpfen Sie sie mit TODO(#issueNumber).
  • Kommentieren Sie alles mit TSDoc.

Don'ts

  • Verwenden Sie Einzüge mit Tabulatoren.
  • Verwenden Sie Unterstriche am Ende von Variablen- oder Funktionsnamen.
    • In älterem Code werden Unterstriche für private oder interne Properties oder Funktionen verwendet. Diese können zwar weiterhin bestehen, es sollte jedoch kein neuer Code gemäß dieser Konvention hinzugefügt werden.
  • Verwenden Sie snake_case.
  • Verwenden Sie doppelte Anführungszeichen (außer beim Schreiben von JSON).
  • Verwenden Sie ein fehlerhaftes TSDoc.
    • Unsere 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).
  • Verwenden Sie string.startsWith. Verwenden Sie stattdessen Blockly.utils.string.startsWith.

TSDoc

Das Blockly-Team verwendet TSDoc, um Code zu annotieren und Dokumentationen zu erstellen. Wir erwarten TSDoc für alle öffentlichen Eigenschaften von Klassen und für alle exportierten Funktionen.

TSDoc-Kommentare müssen mit /** beginnen und mit */ enden, damit sie richtig geparst werden können.

Typen

Typen werden aus TSDoc entfernt, da diese Informationen direkt im TypeScript-Code enthalten sind. Wenn Sie eine der wenigen verbleibenden JavaScript-Dateien bearbeiten, fügen Sie Typanmerkungen gemäß der Closure Compiler-Dokumentation hinzu.

Sichtbarkeit

Funktionen oder Eigenschaften, auf die nur innerhalb der Blockly-Bibliothek zugegriffen werden soll, müssen mit @internal gekennzeichnet werden. Dadurch werden diese Properties nicht in der öffentlichen Dokumentation angezeigt. Andere Sichtbarkeitsmodifikatoren sollten direkt in den TypeScript-Code und nicht in die TSDoc-Datei eingefügt werden.

Attribute

TSDoc-Dateien für Unterkünfte müssen eine Beschreibung der Unterkunft enthalten. Bei selbsterklärenden Properties kann die Beschreibung 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

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