Guide de style

Suivez le guide de style Google TypeScript.

Migration vers TypeScript et ES6

Blockly a été initialement écrit en ES5.1 conformément à une ancienne version, alors actuelle, du guide de style JavaScript de Google. 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 configuré un fichier eslint.config.mjs 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 le linter et npm run format pour exécuter le formateur.
  • 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.
  • 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 lorsque vous écrivez du code JSON).
  • Redéclarez les variables dans les boucles for. Autrement dit, écrivez toujours for (const i = 0; ...) au lieu de for (i = 0; ...).
    • Sinon, vous risquez qu'après un refactoring plus haut dans la fonction, la variable soit orpheline et devienne une variable globale inattendue.
  • Commencez les commentaires par une lettre majuscule et terminez-les par un point.
  • Créez des problèmes GitHub avec des tâches à faire 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 anciens codes utilisent des traits de soulignement pour les propriétés ou fonctions privées ou internes. Bien que ces éléments puissent continuer à exister, aucun nouveau code ne doit être ajouté conformément à cette convention.
  • Utilisez snake_case.
  • Utilisez des guillemets doubles (sauf lorsque vous écrivez du code JSON).
  • Utilisation d'un TSDoc mal formé.
    • Notre TSDoc est automatiquement publié dans notre documentation.
  • Écrivez TODO (username).
    • Créez plutôt des problèmes GitHub avec des tâches à faire 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.

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 rares fichiers JavaScript restants, incluez des annotations de type conformément à la documentation du compilateur Closure.

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 évite que ces propriétés n'apparaissent 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 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 s'ils s'expliquent d'eux-mêmes.

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