Inglês Simples

O que Inglês Simples faz?

Diga o principal com o mínimo de palavras comuns necessárias, e pare. O leitor abre o código para os detalhes.

Seja conciso

• Comece pelo ponto: o que a coisa faz, e por que quando isso não for óbvio.
• Deixe de fora o que o código ou diff já mostra: os arquivos tocados, a ordem dos passos, os casos extremos que o código trata.
• Use a frase compacta da área: "remover ícones não usados", não "remover os ícones que nada usa".
• Diga um fato uma vez.
• Corte palavras, não fatos. Mantenha cada passo que o leitor precisa para ver o problema, e declare a consequência: "essa data pode diferir do dia em que o CI faz o release", não "o cabeçalho é escrito antes do dia do release".

Permaneça claro

Conciso não é enigmático.

• Escreva uma ideia por frase, com sujeito e verbo. Sem ponto e vírgula, enigmas ou slogans, como "sem release, sem tipo".
• Coloque o sujeito primeiro e nomeie quem age: "C++ calcula X", não "X é calculado em C++".
• Use tempos verbais simples, e o presente para o que ainda é verdade: "QML nunca reavalia bindings nele", não "nunca reavaliado".
• Escreva uma condição como Se X, Y.
• Repita o substantivo em vez de "ele", "ela" ou "eles(as)" quando o substantivo estiver distante ou quando mais de um substantivo puder se encaixar.
• Mantenha cláusulas com "que" e "cujo" curtas. Se a cláusula tiver um sujeito longo próprio, escreva uma frase separada: "os pacotes Qt do Debian e Ubuntu não têm isso", não ", que os pacotes Qt do Debian e Ubuntu deixam de fora".
• Diga uma negação diretamente: "ignore valores fora do intervalo", não "não tome valor além do intervalo". Não negue através do objeto: "a edição não emitiu updated()", não "a edição emitiu nenhum updated()". Escreva "nor" apenas após "neither".

Soe nativo

O texto deve parecer algo que um desenvolvedor de língua inglesa escreveu. Se uma frase parecer uma tradução, reescreva-a, mesmo que a reescrita seja uma palavra mais longa.

• Use substantivos compostos, não cadeias de "de": "configurações do app", "o diálogo do arquivo CSV", "pacotes Qt do Debian e Ubuntu". Use possessivo apenas quando nenhum composto funcionar, como "a densidade da folha", e nunca dois seguidos. Permita no máximo um "de" por frase.
• Use o verbo usual da área: "show", "report", "fix", "support", "handle", "check". Não faça o código ser uma pessoa que conta, responde ou carrega. Mantenha "own" para posse no sentido do C++.
• Use uma palavra por conceito: escolha "check" ou "verify", "settings" ou "options", e mantenha.
• Não repita o artigo em uma lista: "o frame e botão de deletar".
• Escreva "must" para um requisito e "can" para uma possibilidade. Evite "should", "may" e "might".
• Escreva "for example", não "e.g.". Use ortografia americana.
• Elimine estas palavras: "leverage" e "utilize" (escreva "use"), "in order to" (escreva "to"), "prior to" (escreva "before"), "ensure", "simply", "just", "easily", "seamlessly", "robust", "powerful", "comprehensive", "functionality", "it is worth noting that", "with this change", "is designed to", "allows you to" (nomeie a coisa e seu verbo), "under the hood", "out of the box".

Antes e depois, de assuntos de commit reais:

Antes	Depois
keep the settings of the app out of documents	don't save app settings in documents
Graph: tell the reader when an export fails	Graph: report export errors
add CardButton, the icon button of the top row of an object	add CardButton, the icon button on an object's top row
Sampler: take no value of a discrete object past its range	Sampler: ignore discrete object values outside the range
stop a full release whose notes carry another day	check the date in the release notes before a full release
build on Ubuntu 26.04, with its packages of Qt	build on Ubuntu 26.04, with its Qt packages

Por tipo de texto

Mensagem de commit

• Escreva o assunto como um imperativo curto que faça sentido sem o diff: "limitar valores do documento aos limites do painel de configurações", não "manter os números de um documento dentro do intervalo do painel".
• Um commit faz uma coisa. Se o corpo precisar de um segundo tópico, divida o commit.
• Comece o corpo com o que o código faz agora, depois um breve porquê.
• Marque um fato além do assunto com "also": "Both reads also skip unknown keys, because newer versions can add some."
• Descarte contexto que o leitor conhece. Não reconte o diff nem defenda a mudança.

Comentário de código

• Não escreva nenhum por padrão. Escreva um por uma razão que o código não mostra, um invariante oculto, ou uma solução alternativa.
• Diga o que o código faz, o que decorre disso, e por que, uma frase curta cada. Pule uma parte que o código já mostra.
• Nomeie a API e não use metáforas. O imperativo é adequado: "pular escritas idênticas: elas ainda atualizam o mtime".
• Escreva o comentário que você daria a um colega que pergunta "por que isso está aqui?". Nomeie o efeito concreto, como "xmin permanece na esquerda", não um resumo como "os limites estão onde estão".

Exemplos:

• Antes: // a vertical list keeps its width a secret, so the style paints a stray handle
• Depois: // a vertical ListView leaves contentWidth at -1, which the style renders as a collapsed handle
• Antes: # the runner's glib and libsystemd need its new glibc, so the AppImage uses the host's glib and libdbus. linuxdeploy still copies the libraries that only they need, so the list names those too
• Depois: # don't bundle glib, libdbus and their dependencies. The AppImage then loads the host's versions. The Ubuntu 26.04 versions need glibc 2.43, which older distros lack.

Documentação

• Descreva o que o código faz hoje. Nomeie a coisa e para que serve, e aponte para o arquivo com os detalhes.
• Coloque três ou mais itens paralelos em uma lista com marcadores.
• Coloque nomes de estilo, módulo e identificador entre acentos graves: FluentWinUI3.
• Marque um fato sobre software de terceiros que pode mudar com "currently" ou a versão: "Debian and Ubuntu Qt packages currently don't have it."

Mensagem de erro: o que aconteceu, a causa se conhecida, e o que fazer. Sem desculpas.

Tooltip: o que o widget define.

Instruções para um agente: uma regra por frase, a condição primeiro.

Deixe intocado

Código, identificadores, comandos, caminhos, mensagens citadas, nomes de produtos, e os nomes de botões, abas, campos e entradas de menu.

Antes de entregar

Leia o texto uma vez como seu leitor. Remova cada frase que não ajude esse leitor. Verifique se cada frase restante é compreensível à primeira leitura e soa como inglês comum.

Se você explicou a mesma coisa no chat, compare as duas versões. Se a versão do chat for mais clara, use-a.