Guide de style Blockly

Suivez le guide de style Google TypeScript.

Migration vers TypeScript et ES6

Blockly a été écrit à l'origine dans ES5.1 conformément à une version plus ancienne et alors actuelle du guide de style JavaScript de Google. Le code nouvellement écrit doit être conforme au guide de style actuel et utiliser les fonctionnalités du langage ES6 telles que let, const et class, ainsi qu'une attribution de déstructuration le cas échéant. Le code existant peut être mis à jour ou non conforme. L'équipe Blockly s'efforce 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 sont plus conformes au guide de style.

À faire

  • Utilisez les outils d'analyse lint et de formatage.
    • Nous utilisons eslint et nous disposons d'un fichier .eslintrc.js configuré avec des règles pour notre style préféré.
    • Le format plus beau est utilisé 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 de mise en forme.
  • Mettez en retrait les espaces, et non les tabulations.
  • Utilisez des points-virgules.
  • Utilisez camelCase pour les variables et les fonctions.
  • Utilisez TitleCase pour les classes.
  • Utilisez ALL_CAPS pour les constantes.
  • Utilisez des accolades pour toutes les structures de contrôle.
    • Exception: vous pouvez omettre les accolades pour les instructions if sur une seule ligne.
  • Utilisez des guillemets simples (sauf lors de l'écriture au format JSON).
  • Redéclarez les variables dans les boucles for. Autrement dit, écrivez toujours for (const i = 0; ...) au lieu de for (i = 0; ...).
    • Sinon, il y a le risque qu'après une refactorisation dans un niveau supérieur de la fonction, la variable devienne orpheline et devienne une surprise globale.
  • Commencez vos commentaires par des 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

  • Mettre en retrait les tabulations
  • 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 ou fonctions privées ou internes. Bien que ceux-ci continuent d'exister, aucun nouveau code ne doit être ajouté en respectant cette convention.
  • Utilisez snake_case.
  • Utilisez des guillemets doubles (sauf lors de l'écriture au format JSON).
  • Utilisez un fichier TSDoc incorrect.
    • Notre TSDoc est publié automatiquement dans notre documentation.
  • Écrivez TODO (username).
    • Créez plutôt des problèmes GitHub avec des tâches à effectuer et associez-les à l'aide de TODO(#issueNumber).
  • Utilisez string.startsWith. Utilisez plutôt Blockly.utils.string.startsWith.

TSDoc

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

Pour être correctement analysés, les commentaires TSDoc doivent commencer par /** et se terminer par */.

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 des annotations de type conformément à la documentation de Closure Compiler.

Visibilité

Les fonctions ou propriétés accessibles uniquement dans la bibliothèque Blockly doivent être annotées avec @internal. Cela empêche ces propriétés d'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

Le TSDoc des propriétés doit inclure une description de la propriété. 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);

distantes

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 cette valeur

Les descriptions peuvent être omises pour les fonctions, les paramètres ou les valeurs de retour si elles 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;
}