Guía de estilo de Blockly

Sigue la guía de estilo de Google TypeScript.

Migración a TypeScript y ES6

Blockly se escribió originalmente en ES5.1 de conformidad con una versión anterior de la Guía de estilo de Google JavaScript de Google. El código recién escrito debe cumplir con la guía de estilo actual y usar funciones del lenguaje ES6, como let, const, class, y desestructurar la asignación cuando corresponda. Es posible que el código existente se actualice o no cumpla con las políticas. El equipo de Blockly intenta tomar la mejor decisión teniendo en cuenta la coherencia del código y la experiencia para los usuarios de la biblioteca. Por ejemplo, es posible que optemos por no cambiar el nombre de las funciones públicas que ya no cumplen con la guía de estilo.

Sí

  • Usa herramientas de análisis con lint 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 linter y npm run format para ejecutar el formateador.
  • Usa sangría con espacios, no con tabulaciones.
  • Usa el punto y coma.
  • 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 declaraciones if de una sola línea.
  • Usa comillas simples (excepto cuando escribas JSON).
  • Vuelve a declarar las variables en los bucles for. Es decir, siempre escribe for (const i = 0; ...) en lugar de for (i = 0; ...).
    • No hacerlo aumenta el riesgo de que, después de una refactorización más alta en la función, la variable quede huérfana y se convierta en una sorpresa global.
  • Comenzar los comentarios con mayúsculas y terminarlos con puntos.
  • Crea problemas de GitHub con los elementos TODO y vincúlalos con TODO(#issueNumber).
  • Anota todo con TSDoc.

Qué no debes hacer

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

TSDoc

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

Los comentarios de TSDoc deben comenzar con /** y terminar con */ para analizarse correctamente.

Tipos

Los tipos se omiten en TSDoc porque esa información está directamente en el código de TypeScript. Si estás editando uno de los pocos archivos JavaScript restantes, incluye anotaciones de tipo de acuerdo con la documentación del compilador de cierres.

Visibilidad

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

Propiedades

El TSDoc para las propiedades debe incluir una descripción de la propiedad. Se puede omitir la descripción en el caso de propiedades que no requieren explicación.

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

remotas

Las anotaciones de las funciones deben incluir

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

Se pueden omitir las descripciones de las funciones, los parámetros o los valores que se muestran si no se explican por su cuenta.

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