Guide de style Blockly

Suivez le guide de style Google TypeScript.

Migration vers TypeScript et ES6

Blockly a été écrit à l'origine en ES5.1 conformément à une version plus ancienne, la version actuelle du style JavaScript de Google guide de démarrage. Le code nouvellement écrit doit respecter le guide de style actuel et utiliser les fonctionnalités du langage ES6 telles que let, const, class et l'affectation destructurante, le cas échéant. Le code existant peut être mis à jour ou rester non conforme. L'équipe Blockly essaie de prendre la meilleure décision en tenant compte de la cohérence du code et de l'expérience des utilisateurs de la bibliothèque. Par exemple, nous pouvons choisir de ne pas renommer les fonctions publiques qui ne respectent plus le guide de style.

À faire

  • Utilisez des outils de linting et de mise en forme.
    • Nous utilisons eslint et avons un .eslintrc.js fichier configuré avec des règles pour notre style préféré.
    • Nous utilisons prettier pour la mise en forme automatique.
    • Exécutez npm run lint pour exécuter l'outil lint et npm run format pour exécuter l'outil. un outil de mise en forme.
  • Utilisez des espaces pour l'indentation, et non des tabulations.
  • Utilisez des points-virgules.
  • Utilisez camelCase pour les variables et les fonctions.
  • Utilisez TitleCase pour les classes.
  • Utilisez ALL_CAPS pour les constantes.
  • Utiliser des accolades pour toutes les structures de contrôle.
    • Exception: vous pouvez omettre les accolades dans les instructions if à une seule ligne.
  • Utilisez des guillemets simples (sauf lors de l'écriture de JSON).
  • Redéclarez les variables dans les boucles for. Autrement dit, écrivez toujours for (const i = 0; ...) au lieu de for (i = 0; ...).
    • Ne pas le faire augmente le risque qu'après une refactorisation plus haut dans le la variable sera orpheline et deviendra une surprise globale.
  • Commencez les commentaires en majuscules et terminez-les par des points.
  • Créez des problèmes GitHub avec des tâches à effectuer et associez-les à l'aide de TODO(#issueNumber).
  • Annotez tout avec TSDoc.

À éviter

  • Utilisez des tabulations pour l'indentation.
  • Utilisez des traits de soulignement à la fin des noms de variables ou de fonctions.
    • Certains codes antérieurs utilisent des traits de soulignement pour les propriétés privées ou internes ou fonctions. Bien que celles-ci puissent continuer d'exister, aucun nouveau code ne doit être en suivant cette convention.
  • Utilisez snake_case.
  • Utilisez des guillemets doubles (sauf lors de l'écriture au format JSON).
  • Utilisation d'un TSDoc mal formé.
    • Notre TSDoc est publié automatiquement dans notre documentation.
  • Écrivez TODO (username).
    • Créez plutôt des problèmes GitHub avec TODO et associez-les à l'aide de TODO(#issueNumber)
  • Utilisez string.startsWith. Utilisez Blockly.utils.string.startsWith à la place.

TSDoc

L'équipe Blockly utilise TSDoc pour annoter notre code et générer de la documentation. Nous attendons TSDoc pour toutes les propriétés publiques des classes, et pour toutes les fonctions exportées.

Les commentaires TSDoc doivent commencer par /** et se terminer par */ pour être analysés correctement.

Types

Les types sont omis de TSDoc, car ces informations se trouvent directement dans le code TypeScript. Si vous modifiez l'un des quelques fichiers JavaScript restants, incluez d'annotations de type Closure Compiler documentation.

Visibilité

Les fonctions ou propriétés qui ne doivent être accessibles que dans la bibliothèque Blockly doivent être annotées avec @internal. Cela empêche ces propriétés apparaître dans la documentation publique. Les autres modificateurs de visibilité doivent être placés directement dans le code TypeScript, et non dans le TSDoc.

Propriétés

Les TSDoc pour les propriétés doivent inclure une description de la propriété. La la description peut être omise pour les propriétés explicites.

/**
  *   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);

Fonctions

Les annotations pour les fonctions doivent inclure

  • Description de la fonction
  • Une balise @param par paramètre, y compris :
    • Nom
    • Description
  • Une balise @returns si la fonction renvoie une valeur, avec une description de la valeur renvoyée.

Les descriptions peuvent être omises pour les fonctions, les paramètres ou les valeurs de retour si elles sont sont explicites.

Exemple :

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