Guía de estilo

Sigue la guía de estilo de TypeScript de Google.

Migración a TypeScript y ES6

Blockly se escribió originalmente en ES5.1 de conformidad con una versión anterior y vigente de la guía de estilo 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 intenta tomar la mejor decisión teniendo en cuenta la coherencia del código y la experiencia de 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 el guía de estilo.

Qué debes hacer

• Usa herramientas de linting y formato.
  • Usamos eslint y tenemos un archivo eslint.config.mjs configurado con reglas para nuestro estilo preferido.
  • Usamos prettier para el formato automático.
  • Ejecuta npm run lint para ejecutar el lint y npm run format para ejecutar el formato.
• Usa espacios, no tabulaciones, para la sangría.
• Usa puntos y comas.
• Usa camelCase para las 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 las variables en los 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

• Usa tabulaciones para crear sangría.
• Usa guiones bajos al final de los nombres de las variables o funciones.
  • Algunos códigos anteriores usan guiones bajos para propiedades o funciones privadas o internas. 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 anotar nuestro código y 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 se encuentra directamente en el código de TypeScript. Si estás editando uno de los pocos archivos JavaScript restantes, incluye anotaciones de tipo según la documentación del compilador de Closure.

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. Otros modificadores de visibilidad se deben colocar directamente en el código de TypeScript, no en TSDoc.

Propiedades

El TSDoc de 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 lo siguiente:

• Una descripción de la función
• Una etiqueta @param por parámetro, incluido
  • 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 se explican por sí mismas.

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