Guía de estilo de Blockly

Sigue el estilo de TypeScript de Google .

Migración a TypeScript y ES6

Blockly se escribió originalmente en ES5.1 de conformidad con una versión la versión actual del diseño de JavaScript de Google . El código escrito recientemente debe cumplir con el manual de estilo actual y usar las funciones del lenguaje ES6, como let, const, class y la asignación de desestructuración cuando corresponda. Es posible que el código existente se actualice o que no cumpla con los requisitos. El equipo de Blockly Trata de tomar la mejor decisión teniendo en cuenta la coherencia del código y el para los usuarios de la biblioteca, por ejemplo, podríamos optar por no cambiar el nombre para las funciones públicas que ya no cumplen con la guía de estilo.

Qué debes hacer

  • Usa herramientas de linting y formato.
    • Usamos eslint y tenemos un archivo .eslintrc.js configurado con reglas para nuestro estilo preferido.
    • Usamos prettier para el formato automático.
    • Ejecuta npm run lint para ejecutar el linter y npm run format para ejecutar el formateador.
  • Usa espacios, no tabulaciones.
  • Usa puntos y comas.
  • Usa camelCase para variables y funciones.
  • Usa TitleCase para las clases.
  • Usa ALL_CAPS para las constantes.
  • Usa llaves para todas las estructuras de control.
    • Excepción: Puedes omitir las llaves para las sentencias if de una sola línea.
  • Usa comillas simples (excepto cuando escribas JSON).
  • Vuelve a declarar variables en bucles for. Es decir, siempre escribe for (const i = 0; ...) en lugar de for (i = 0; ...).
    • De lo contrario, aumenta el riesgo de que, después de una refactorización más arriba en la función, la variable quede huérfana y se convierta en una variable global inesperada.
  • Comienza los comentarios con mayúsculas y termínalos con puntos.
  • Crea problemas de GitHub con tareas pendientes y vincúlalos con TODO(#issueNumber).
  • Anota todo con TSDoc.

Qué no debes hacer

  • Aplicar sangría a tabulaciones
  • Usa guiones bajos al final de los nombres de las variables o funciones.
    • En algunos códigos anteriores, se usan guiones bajos para propiedades privadas o internas, o funciones. Si bien es posible que sigan existiendo, no se debe agregar código nuevo siguiendo esta convención.
  • Utiliza snake_case.
  • Usa comillas dobles (excepto cuando escribas JSON).
  • Usa un TSDoc con el formato incorrecto.
    • Nuestro TSDoc se publica automáticamente como parte de nuestra documentación.
  • Escribe TODO (username).
    • En su lugar, crea problemas de GitHub con tareas pendientes y vincúlalos con TODO(#issueNumber).
  • Utiliza string.startsWith. Usa Blockly.utils.string.startsWith en su lugar.

TSDoc

El equipo de Blockly usa TSDoc para agregar anotaciones al código. generar documentación. Esperamos TSDoc para todas las propiedades públicas de las clases y para todas las funciones exportadas.

Los comentarios de TSDoc deben comenzar con /** y terminar con */ para que se analicen correctamente.

Tipos

Los tipos se omiten de TSDoc porque esa información está en el código de TypeScript. directamente. Si estás editando uno de los pocos archivos JavaScript restantes, incluye anotaciones de tipo según la documentación de Closure Compiler.

Visibilidad

Funciones o propiedades a las que solo se debe acceder dentro de la biblioteca de Blockly debe anotarse con @internal. Esto evita que estas propiedades aparezcan en la documentación pública. Otra visibilidad modificadores se deben colocar directamente en el código de TypeScript, no en el TSDoc.

Propiedades

El TSDoc para las propiedades debe incluir una descripción de la propiedad. Se puede omitir la descripción para las propiedades que se explican por sí mismas.

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

Funciones

Las anotaciones de las funciones deben incluir

  • Descripción de la función
  • Una etiqueta @param por parámetro, incluido
    • Nombre
    • Descripción
  • Una etiqueta @returns si la función devolverá un valor, con una descripción del valor que se muestra.

Se pueden omitir las descripciones de funciones, parámetros o valores que se muestran en los siguientes casos: no requieren explicación.

Por ejemplo:

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