Pular para o conteúdo principal

Princípios de codificação

Mensagens de erro​

Uma boa mensagem de erro informa ao usuário o que fazer a seguir. Qualquer ambiguidade nos erros lançados pelas APIs públicas do Playground levará os desenvolvedores a abrir issues.

Considere um erro de rede, por exemplo: podemos inferir o tipo de erro e exibir uma mensagem relevante resumindo os próximos passos?

  • Erro de rede: "Sua conexão com a internet oscilou. Tente recarregar a página."
  • 404: "Não foi possível encontrar o arquivo".
  • 403: "O servidor bloqueou o acesso ao arquivo".
  • CORS: esclareça que é um recurso de segurança do navegador e adicione um link para uma explicação detalhada (no MDN ou outra fonte confiável). Sugira que o usuário mova o arquivo para outro lugar, como raw.githubusercontent.com, e crie um link para um recurso que explique como configurar os cabeçalhos CORS em seus servidores.

Lidamos com a formatação e o linting do código automaticamente. Relaxe, digite e deixe as máquinas fazerem o trabalho.

API Pública​

O Playground visa manter o escopo de API o mais restrito possível.

APIs públicas são fáceis de adicionar e difíceis de remover. Leva apenas um PR para introduzir uma nova API, mas pode levar mil para removê-la, especialmente se outros projetos já a consumiram.

  • Não exponha funções, classes, constantes ou outros componentes desnecessários.

Blueprints​

Blueprints são a principal forma de interagir com o Playground. Estes arquivos JSON descrevem um conjunto de passos que o Playground executa em ordem.

Diretrizes​

Os passos do Blueprint devem ser concisos e focados. Eles devem fazer uma coisa e fazê-la bem.

  • Se você precisar criar um novo passo, tente refatorar um existente primeiro.
  • Se isso não for suficiente, garanta que o novo passo entregue uma nova capacidade. Não replique a funcionalidade de passos existentes.
  • Assuma que o passo será chamado mais de uma vez.
  • Assuma que ele será executado em uma ordem específica.
  • Adicione testes unitários para verificar isso.

Blueprints devem ser intuitivos e diretos.

  • Não exija argumentos que podem ser opcionais.
  • Use argumentos simples. Por exemplo, slug em vez de path.
  • Defina constantes em arquivos JSON virtuais — não modifique arquivos PHP.
  • Defina um tipo TypeScript para o Blueprint. É assim que o Playground gera seu esquema JSON.
  • Escreva uma função para lidar com um passo do Blueprint. Aceite o argumento do tipo que você definiu.
  • Forneça um exemplo de uso na docstring. Ele é refletido automaticamente na documentação.