Guia de estilo do Exercism

Este documento funciona como um guia de estilo para a linguagem e a redação usadas nos exercícios.

Aplicação

Estas regras devem ser seguidas em todos os exercícios. Descrições e casos de teste existentes podem ser atualizados para segui-las, sem exigir casos de teste de "substituição".

Consistência dentro de um exercício

Existem alguns termos que têm várias grafias válidas (por exemplo, "lower case" em vez de "lowercase"). Quando este documento não tiver acordado um estilo consistente, o uso precisa ser consistente dentro de um exercício.

Exceções

Os exercícios podem fugir destas regras se houver consenso geral entre os mantenedores de que isso é razoável. Por exemplo, um exercício sobre conversão entre unidades diferentes pode optar por não usar medidas do SI.

Linguagem

Todo o conteúdo deve ser escrito em inglês americano, que difere do inglês britânico de várias maneiras. No futuro podem surgir outras traduções, mas a linguagem "oficial" do Exercism é o inglês americano.

Medidas

Todas as unidades de medida devem ser unidades do SI ou derivadas do SI.

Abreviações, acrônimos e siglas

Abreviações, acrônimos e siglas costumam ser mais difíceis de entender do que outras formas de dizer a mesma coisa, e podem afastar quem está tentando aprender.

Muitas abreviações são jargão. Evite jargão onde for possível, usando outra forma de expressar a mesma ideia. Não use abreviações a menos que:

  • O termo abreviado seja mais conhecido do que o termo completo
  • O texto fique excessivamente prolixo sem a abreviação

Ao usar abreviações, explique sempre o que o termo significa na primeira vez em que ele aparecer. Isso muitas vezes, mas nem sempre, inclui escrever a abreviação por extenso. Raramente basta apenas escrevê-la por extenso.

Aqui estão algumas regras de exemplo:

  • Prefira "if I recall correctly" a "IIRC"
  • Prefira "as far as I know" a "AFAIK"
  • Prefira "queue" a "FIFO" e "stack" a "FILO"
  • Em vez de descrever uma interface como "RESTful", descreva suas propriedades específicas
  • Se você precisar usar "CRUD", explique que a sigla vem de Create, Read, Update, Delete e que essas são as ações básicas em bancos de dados convencionais

E alguns exemplos de bom uso:

  • "HyperText Markup Language (HTML) is the language used to describe document structure and content on the web" (por extenso e explicado)
  • "DNA, a set of chemical instructions that influence how our bodies are constructed" (DNA não é escrito por extenso porque "deoxyribonucleic acid" provavelmente não ajudaria a explicar o que é o DNA para o nosso público)
  • "NASA, the United States' space agency, launched the Mariner 2 space probe in..." (NASA não é escrita por extenso porque "National Aerospace and Space Administration" é muito mais conhecida pela sigla do que pelo nome completo)
  • "The Department of Motor Vehicles (DMV) is filled with sloths. That's why everything takes forever at the DMV" (Defina o DMV na primeira vez em que ele for usado)

Gramática

Vírgula de Oxford

Use a "vírgula de Oxford" (também conhecida como vírgula serial) em listas. Por exemplo, em vez de "I love my parents, Lady Gaga and Humpty Dumpty", escreva "I love my parents, Lady Gaga, and Humpty Dumpty". Você também pode gostar desta imagem como explicação.

Exceções

Algumas abreviações são consideradas comuns, úteis e não técnicas o bastante para que tenhamos decidido permiti-las:

  • e.g. ou eg
  • i.e. ou ie
  • etc. ou etc
  • docs

Contrações (por exemplo, "won't", "I'm", "that's") devem ser usadas com moderação, se não evitadas, nas descrições dos exercícios, mas não são restritas em outros textos do site (por exemplo, textos de páginas institucionais, mentoria).

Muitos guias de estilo do inglês americano dizem que as abreviações "i.e." e "e.g." devem ser seguidas de vírgula (veja, por exemplo, este tópico do StackExchange). Isso é permitido, mas não obrigatório nos textos do Exercism.

Escolha das palavras

Termos matemáticos e de jargão

Sempre que termos matemáticos forem usados, eles devem ser explicados ou substituídos por termos que exijam menos conhecimento de domínio.

Exemplos:

  • Em vez de usar "natural numbers", devemos usar "positive whole numbers".
  • Se quisermos usar a expressão "rational numbers", ela precisa ser explicada na introdução do exercício.
  • Em vez de usar a palavra range (que pode ter significados diferentes em contextos diferentes), use "x < ? < y (greater than x and less than y)".
  • Em vez de usar "esoteric terms", use a expressão "terms not understood by the majority of people".

Código

Todo código deve ser formatado de forma consistente, seguindo as convenções de estilo da sua trilha. Quando possível, essas convenções da trilha devem corresponder às convenções de estilo preferidas da linguagem.