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 depath
. - 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.