Guia de estilo do Exercism

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

Aplicação

Estas regras devem ser seguidas em todos os exercícios. As descrições e os casos de teste existentes podem ser atualizados para cumprir estas regras, sem que seja preciso criar casos de teste de "substituição".

Consistência dentro de um exercício

Há termos que admitem mais do que uma grafia válida (por exemplo, "lower case" vs "lowercase"). Quando este documento não estabelece um estilo consistente, esses termos têm de ser usados de forma consistente dentro de cada exercício.

Exceções

Os exercícios podem afastar-se destas regras se houver um consenso geral entre os responsáveis pela manutenção 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.

Língua

Todo o conteúdo deve ser escrito em inglês dos Estados Unidos, que difere do inglês do Reino Unido de várias formas. No futuro poderão surgir outras traduções, mas a língua "oficial" do Exercism é o inglês dos Estados Unidos.

Medidas

Todas as unidades de medida têm de ser unidades do SI ou derivadas do SI.

Abreviaturas, acrónimos e siglas

As abreviaturas, os acrónimos e as siglas são muitas vezes mais difíceis de compreender do que outras formas de dizer a mesma coisa, e podem afastar quem está a tentar aprender.

Muitas abreviaturas são jargão. Evita o jargão sempre que possível, recorrendo a outras palavras. Não uses abreviaturas, exceto se:

  • A forma abreviada for mais conhecida do que a forma não abreviada
  • O texto ficar demasiado extenso sem a abreviatura

Quando usares abreviaturas, explica sempre o que o termo significa na primeira vez que aparecer. Muitas vezes, mas nem sempre, isso passa por escrever a abreviatura por extenso. Raramente será suficiente escrever apenas a abreviatura por extenso.

Eis algumas regras de exemplo:

  • Prefere "if I recall correctly" a "IIRC"
  • Prefere "as far as I know" a "AFAIK"
  • Prefere "queue" a "FIFO" e "stack" a "FILO"
  • Em vez de descreveres uma interface como "RESTful", descreve as suas propriedades específicas
  • Se tiveres mesmo de usar "CRUD", explica que significa Create, Read, Update, Delete e que estas são as ações básicas nas bases de dados padrão

E alguns exemplos de bom uso:

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

Gramática

Vírgula de Oxford

Usa a "vírgula de Oxford" (também conhecida como vírgula serial) nas enumerações. Por exemplo, em vez de "I love my parents, Lady Gaga and Humpty Dumpty", escreve "I love my parents, Lady Gaga, and Humpty Dumpty". Também podes gostar de ver esta imagem como explicação.

Exceções

Algumas abreviaturas são consideradas suficientemente comuns, úteis e pouco técnicas para que tenhamos decidido permiti-las:

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

As contrações (por exemplo, "won't", "I'm", "that's") devem ser usadas com moderação, ou mesmo evitar-se, nas descrições dos exercícios, mas não há restrições no restante texto do site (por exemplo, textos do site, mentoria).

Muitos guias de estilo de inglês americano afirmam que as abreviaturas "i.e." e "e.g." devem ser seguidas de vírgula (ver, por exemplo, este tópico do StackExchange). No texto do Exercism, isso é permitido, mas não obrigatório.

Escolha de palavras

Termos matemáticos e jargão

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

Exemplos:

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

Código

Todo o código deve ser formatado de forma consistente, seguindo as convenções de estilo do respetivo percurso. Sempre que possível, essas convenções de todo o percurso devem corresponder às convenções de estilo preferidas da linguagem.