Ir al contenido principal

Principios de codificación

Mensajes de error​

Un buen mensaje de error informa al usuario de los siguientes pasos a seguir. Cualquier ambigüedad en los errores lanzados por las APIs públicas de Playground incitará a los desarrolladores a abrir issues.

Considera un error de red, por ejemplo, ¿podemos inferir el tipo de error y mostrar un mensaje relevante que resuma los siguientes pasos?

  • Error de red: "Tu conexión a internet ha fallado. Intenta recargar la página".
  • 404: "No se ha podido encontrar el archivo".
  • 403: "El servidor ha bloqueado el acceso al archivo".
  • CORS: aclara que es una característica de seguridad del navegador y añade un enlace a una explicación detallada (en MDN u otra fuente fiable). Sugiere al usuario que mueva su archivo a otro lugar, como raw.githubusercontent.com, y enlaza a un recurso que explique cómo configurar las cabeceras CORS en sus servidores.

Nos encargamos del formato del código y del linting automáticamente. Relájate, escribe y deja que las máquinas hagan el trabajo.

API Pública​

Playground tiene como objetivo mantener el ámbito de la API lo más reducido posible.

Las APIs públicas son fáciles de añadir y difíciles de eliminar. Solo se necesita un PR para introducir una nueva API, pero puede que se necesiten mil para eliminarla, especialmente si otros proyectos ya la han consumido.

  • No expongas funciones, clases, constantes u otros componentes innecesarios.

Blueprints​

Los Blueprints son la forma principal de interactuar con Playground. Estos archivos JSON describen un conjunto de pasos que Playground ejecuta en orden.

Directrices​

Los pasos de los Blueprints deben ser concisos y centrados. Deben hacer una cosa y hacerla bien.

  • Si necesitas crear un nuevo paso, intenta refactorizar uno existente primero.
  • Si eso no es suficiente, asegúrate de que el nuevo paso ofrezca una nueva capacidad. No repliques la funcionalidad de los pasos existentes.
  • Asume que el paso se llamará más de una vez.
  • Asume que se ejecutará en un orden específico.
  • Añade pruebas unitarias para verificarlo.

Los Blueprints deben ser intuitivos y directos.

  • No requieras argumentos que puedan ser opcionales.
  • Usa argumentos sencillos. Por ejemplo, slug en lugar de path.
  • Define constantes en archivos JSON virtuales, no modifiques archivos PHP.
  • Define un tipo de TypeScript para el Blueprint. Así es como Playground genera su esquema JSON.
  • Escribe una función para manejar un paso de Blueprint. Acepta el argumento del tipo que definiste.
  • Proporciona un ejemplo de uso en la cadena de documentación. Se refleja automáticamente en la documentación.