Conceitos

Os conceitos são as coisas que alguém que programa precisa entender para ser fluente em uma linguagem. Os conceitos são ensinados pelos exercícios de conceito e servem como pré-requisitos para exercícios de conceito e de prática. Os conceitos são posicionados em um mapa de conceitos quando exibidos para o estudante.

Metadados

Os metadados de um conceito são definidos na chave concepts do arquivo config.json. Os metadados definem o UUID, o slug e outras informações do conceito.

Exemplo

{
  "concepts": [
    {
      "uuid": "b9a421b2-c5ff-4213-bd6d-b886da31ea0d",
      "slug": "numbers",
      "name": "Numbers"
    }
  ]
}

Arquivos

Cada conceito tem seu próprio diretório dentro do diretório concepts da trilha. O nome do diretório do conceito deve corresponder à propriedade slug do conceito, conforme definido no arquivo config.json.

Um conceito tem dois tipos de arquivos:

Arquivos de documentação

Esses arquivos são apresentados ao estudante para ajudar a explicar o conceito.

  • about.md: fornece informações sobre o conceito para um estudante que já concluiu o exercício de conceito correspondente, para aprender e consultar depois (obrigatório)
  • introduction.md: fornece uma breve introdução para um estudante que ainda não concluiu o exercício de conceito correspondente (obrigatório)
  • links.json: fornece links úteis com mais leituras ou informações sobre um conceito (obrigatório)

Arquivos de metadados

Esses arquivos não são apresentados ao estudante, mas são usados para definir os metadados do conceito.

  • .meta/config.json: contém informações de metadados sobre o conceito (obrigatório)

Exemplo

concepts
└── numbers
    ├── .meta
    |   └── config.json
    ├── about.md
    ├── introduction.md
    └── links.json

Arquivo: about.md

Objetivo: fornecer informações mais detalhadas sobre o conceito para um estudante que já concluiu o exercício de conceito correspondente, para aprender e consultar depois.

Presença: obrigatório

Depois de concluir o exercício de conceito correspondente (também conhecido como "aprender" um conceito), a página do conceito mostra o conteúdo do arquivo about.md em vez do arquivo introduction.md. O arquivo about.md deve dar ao estudante informações abrangentes sobre o que ele precisa saber para ser fluente no conceito. No mínimo, esse arquivo deve conter todas as informações apresentadas no documento introduction.md dos conceitos.

Se o conceito apresenta uma sintaxe nova, devem ser incluídos exemplos dessa sintaxe. O estudante não deve precisar seguir muitos links para adquirir o conhecimento que o arquivo tenta transmitir. Em vez disso, o about.md deve conter informações suficientes para ser compreensível dentro do seu contexto.

O arquivo about.md não se limita ao escopo do exercício de conceito correspondente. O conteúdo pode exigir conhecimento de outros conceitos que serão apresentados mais adiante. Se outros conceitos forem mencionados, deve-se linkar para as respectivas introduções (veja links internos para mais detalhes).

Aqui estão alguns exemplos do que pode ser abordado.

  • Usos populares de um conceito
  • Armadilhas comuns no uso de um conceito (por exemplo, não considerar a segurança de threads)
  • Limitações de uso que podem pegar de surpresa o desenvolvedor desavisado
  • Abordagens alternativas tratadas em outros conceitos (por exemplo, o conceito de recursão pode mencionar que o conceito de Funções de Alta Ordem oferece uma abordagem alternativa para problemas semelhantes)
  • Concessões feitas para facilitar o aprendizado ou para se adaptar ao ambiente do Exercism, por exemplo, várias classes em um único arquivo
  • Recursos semelhantes com os quais o conceito pode ser confundido
  • Características de desempenho e uso de memória, quando isso for uma consideração comum naquela linguagem
  • Não faça referência a um exercício no texto, pois este arquivo é exibido fora do contexto de um exercício.

Não é o objetivo do arquivo about.md fornecer um conjunto completo de informações sobre o conceito. Como exemplo, imagine uma linguagem que tem alguns recursos mais antigos que programadores experientes (e talvez até a documentação ou a especificação oficial) recomendam não usar mais. Detalhar esses recursos estaria fora do escopo do arquivo about.md, porque eles não são relevantes para alcançar a fluência. No entanto, os mantenedores podem optar por adicionar um pequeno bloco para reconhecer os padrões antigos, caso o estudante possa encontrá-los com frequência por aí. Esse bloco, porém, deve ser marcado como tal.

O arquivo about.md DEVE ter uma estrutura clara, especialmente quando contém muitas informações. No futuro, também haverá suporte para marcar partes como "tópicos avançados", a fim de destacá-las para os estudantes interessados sem sobrecarregar os demais.

Exemplo

# About

There are two different kinds of numbers in Elixir - integers and floats.

Floats are numbers with one or more digits behind the decimal separator. They use the 64-bit double precision floating-point format.

```elixir
float = 3.45
# => 3.45
```

Elixir also supports the scientific notation for floats.

```elixir
1.25e-2
# => 0.0125
```

## Rounding errors

Floats are infamous for their rounding errors.

```elixir
0.1 + 0.2
# => 0.30000000000000004
```

However, those kind of errors are not specific to Elixir. They happen in all programming languages. This is because all data on our computers is stored and processed as binary code. In binary, only fractions whose denominator can be expressed as `2^n` (e.g. `1/4`, `3/8`, `5/16`) can be expressed exactly. Other fractions are expressed as estimations.

```elixir
# 3/4
Float.ratio(0.75)
# => {3, 4}

# 3/5
Float.ratio(0.6)
# => {5404319552844595, 9007199254740992}
```

You can learn more about this problem at [0.30000000000000004.com][0.30000000000000004.com]. The [Float Toy page][evanw.github.io-float-toy] has a nice, graphical explanation how a floating-point number's bits are converted to an actual floating-point value.

Arquivo: introduction.md

Objetivo: fornecer uma breve introdução para um estudante que ainda não concluiu o exercício de conceito correspondente.

Presença: obrigatório

Este arquivo é exibido se o estudante ainda não concluiu o exercício de conceito correspondente. Ele deve fornecer uma breve introdução ao conceito.

  • Deve ser fornecida apenas a informação necessária para entender os fundamentos do conceito. Informações extras devem ficar para o documento about.md.
  • Links devem ser usados com moderação, se é que devem. Embora um link explicando um tópico complexo como recursão possa ser útil, para a maioria dos conceitos os links trazem mais informação do que o necessário, então o ideal é explicar as coisas de forma concisa no próprio texto.
  • Termos técnicos adequados devem ser usados para que o estudante possa pesquisar mais informações com facilidade.
  • Exemplos de código só devem ser usados para apresentar uma sintaxe nova (o estudante não deve precisar procurar na web exemplos de sintaxe). Nos outros casos, forneça descrições ou links em vez de código.
  • Não faça referência a um exercício no texto, pois este arquivo é exibido fora do contexto de um exercício.

Exemplo

# Introduction

One of the key aspects of working with numbers in C# is the distinction between integers and floating-point numbers (numbers with zero or more digits after the decimal separator).

The two most commonly used numeric types in C# are `int` (a 32-bit integer) and `double` (a 64-bit floating-point number).

```csharp
int i = 123;
double d = 54.29;
```

Objetivo: fornecer links úteis com mais leituras ou informações sobre um conceito.

Presença: obrigatório

Podem ser documentações oficiais, um bom tutorial, etc. Esses links não substituem os links mais contextuais dentro do arquivo about.md de um conceito, mas oferecem um conjunto rápido de referências gerais para o estudante.

Cada link deve conter os seguintes campos:

  • url: a URL para a qual o link aponta.
  • description: uma descrição do link, exibida como o texto do link.

Os links também podem ter, opcionalmente, um campo icon_url, que pode ser usado para personalizar o ícone exibido quando o link é mostrado. Se não for especificado, o ícone padrão é o favicon.

[
  {
    "url": "https://docs.microsoft.com/en-us/dotnet/csharp/tutorials/intro-to-csharp/numbers-in-csharp-local",
    "description": "Numbers in C#"
  },
  {
    "url": "https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/builtin-types/integral-numeric-types",
    "description": "Integral numeric types",
    "icon_url": "http://test.org/icon.png"
  }
]

Arquivo: .meta/config.json

Objetivo: contém informações de metadados sobre o conceito.

Presença: obrigatório

Este arquivo contém informações de metadados sobre o conceito:

  • authors: o(s) nome(s) de usuário do GitHub do(s) autor(es) do conceito (obrigatório)
    • Inclua os revisores se as revisões deles mudarem substancialmente o conceito (a ponto de parecer que "vocês chegaram lá juntos")
  • contributors: o(s) nome(s) de usuário do GitHub do(s) contribuidor(es) do conceito (opcional)
    • Inclua os revisores se as revisões deles forem significativas, acionáveis ou aplicadas.
  • blurb: uma breve descrição deste conceito. O comprimento deve ser <= 350. Markdown não é suportado (obrigatório)

Se alguém for ao mesmo tempo autor e contribuidor, liste essa pessoa apenas como autor.

Exemplo

{
  "authors": ["FSharpForever"],
  "contributors": ["IWantToHelp"],
  "blurb": "F# has two types of numbers: integers and floating-point numbers."
}

Observe que:

  • A ordem dos autores e contribuidores não é significativa e não tem significado.