Princípios de codificação

Mensagens de erro

Uma boa mensagem de erro informa o usuário sobre os próximos passos a serem seguidos. 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 adicione um link para um recurso explicando como configurar os cabeçalhos CORS em seus servidores.

Nós lidamos com a formatação de código e o linting 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. Basta um PR para introduzir uma nova API, mas pode ser necessário 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 de um Blueprint devem ser concisos e focados. Devem fazer uma coisa e fazê-la bem.

• Se precisar criar um novo passo, tente refatorar um existente primeiro.
• Se isso não for suficiente, garanta que o novo passo ofereça uma nova capacidade. Não replique a funcionalidade de passos existentes.
• Suponha que o passo será chamado mais de uma vez.
• Suponha 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 possam 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 doc string. Ele é refletido automaticamente nos documentos.