Filosofia

Esta lista inclui princípios gerais que o projeto deveria respeitar. A lista não é abrangente. Alguns desses princípios são óbvios, mas são mencionados para garantir a completude.

Gestão do Projeto

Estabelecer expectativas claras. Mostrar as intenções e decisões do projeto com bastante antecedência. Nada deve ser uma surpresa.
Comunicação clara das decisões. A equipe pode avaliar opções e tomar decisões por meio de canais privados. Embora a equipe tente manter discussões em canais públicos como discussões no Github ou no Discord, verificações privadas frequentes são comuns, dada a natureza de uma empresa privada. Quando decisões ocorrem por meio de canais privados, a equipe precisa se comprometer a comunicar essas decisões usando canais públicos.

Técnico

Erros devem sugerir correções e sugestões quando possível. Essas devem ser inferidas e filtradas a partir do uso para reduzir a apresentação de mensagens irrelevantes e inúteis.
Mensagens de erro únicas e específicas. Sem mensagens de erro genéricas. Isso ajuda os usuários a entenderem o que deu errado e deve fornecer aos mantenedores um local de chamada único e as informações necessárias para depuração.
Otimizar a API. Questione a existência de todas as opções. Elas são realmente necessárias? Podem ser combinadas? Como podemos reduzir as ramificações de código?
Reduzir jargões. Não assuma que os usuários entenderão termos específicos. Esforce-se para fornecer significados precisos para especialistas e iniciantes. Por exemplo, use “caractere” onde normalmente usaria “token” ao gerar erros de análise sintática.
Utilizar verbosidade ao nomear comandos e opções. Sem abreviações desnecessárias e confusas.
Usar termos inclusivos Use pronomes de gênero neutro. Evite termos pejorativos relacionados a capacidades. Evite termos que possam ser considerados insensíveis.
Construir para clientes genéricos. Não assuma que o terminal consumirá somente saídas usando códigos ANSI. Use abstrações que possam ser generalizadas para visualização em uma IDE, navegador ou outros ambientes.
A saída do terminal não deve ser ambígua. Ao projetar a saída do terminal, não se baseie apenas em sinais de formatação como cores. Sempre use uma combinação de formatação, símbolos e espaçamento. Se todos os códigos ANSI forem removidos, toda a saída ainda deve ser compreensível.