Blockly-Styleguide

Folgen Sie dem Google TypeScript-Stil .

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 gegebenenfalls die Destrukturierungszuweisung verwenden. Vorhandener Code kann aktualisiert oder nicht konform bleiben. Das Blockly-Team die beste Entscheidung unter Berücksichtigung der konsistenten Codes und der für die Nutzer der Bibliothek. So können wir beispielsweise entscheiden, öffentlichen Funktionen, die dem Styleguide nicht mehr entsprechen.

Do

  • Linting- und Formatierungstools verwenden.
    • Wir verwenden eslint und haben eine .eslintrc.js-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 auszuführen, und npm run format, um den Formatierer.
  • 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 Klammern für alle Kontrollstrukturen.
    • Ausnahme: Bei einzeiligen if-Anweisungen können Sie die Klammern weglassen.
  • Verwenden Sie einfache Anführungszeichen (außer beim Schreiben von JSON).
  • Deklarieren Sie Variablen in for-Schleifen neu. Schreiben Sie 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.
  • Beginnen Sie Kommentare mit Großbuchstaben und beenden Sie sie mit einem Punkt.
  • Erstellen Sie GitHub-Probleme mit TODOs und verknüpfen Sie sie mit TODO(#issueNumber).
  • Annotieren 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).
  • Fehlerhaftes TSDoc verwenden.
    • 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 annotiert mit TSDoc unseren Code und die Dokumentation zu generieren. 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 korrekt geparst werden.

Typen

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

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 selbsterklärend sein.

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