Conceitos

Os conceitos são aquilo que um programador precisa de compreender para ser fluente numa linguagem. Os conceitos são ensinados nos Exercícios de Conceito e servem de pré-requisitos para Exercícios de Conceito e de Prática. Os conceitos são colocados num mapa de conceitos quando são apresentados ao estudante.

Metadados

Os metadados de um conceito são definidos na chave concepts do ficheiro config.json. Os metadados definem o UUID, o slug e muito mais do conceito.

Exemplo

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

Ficheiros

Cada conceito tem o seu próprio diretório dentro do diretório concepts da track. O nome do diretório do conceito tem de corresponder à propriedade slug do conceito, tal como definida no ficheiro config.json.

Um conceito tem dois tipos de ficheiros:

Ficheiros de documentação

Estes ficheiros são apresentados ao estudante para ajudar a explicar o conceito.

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

Ficheiros de metadados

Estes ficheiros não são apresentados ao estudante; servem 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

Ficheiro: about.md

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

Presença: obrigatório

Depois de concluir o exercício de conceito correspondente (ou seja, de "aprender" um conceito), a página do conceito passa a mostrar o conteúdo do ficheiro about.md em vez do ficheiro introduction.md. O ficheiro about.md deve fornecer aos estudantes informações abrangentes sobre o que precisam de saber para serem fluentes no conceito. No mínimo, este ficheiro deve conter toda a informação introduzida no documento introduction.md dos conceitos.

Se o conceito introduzir sintaxe nova, deve incluir exemplos dessa sintaxe. O estudante não deve ter de seguir muitas ligações para adquirir o conhecimento que o ficheiro procura transmitir. Em vez disso, o about.md deve conter informação suficiente para ser compreensível no seu contexto.

O ficheiro about.md não se limita ao âmbito do exercício de conceito correspondente. O conteúdo pode exigir conhecimentos de outros conceitos que serão introduzidos mais tarde. Se forem mencionados outros conceitos, deve ligar-se às respetivas introduções (ver ligações internas para mais detalhes).

Eis alguns exemplos do que pode ser abordado.

  • Utilizações populares de um conceito
  • Armadilhas comuns na utilização de um conceito (por exemplo, não considerar a segurança entre threads)
  • Limitações de utilização que podem apanhar desprevenido o programador incauto
  • Abordagens alternativas tratadas noutros conceitos (por exemplo, o conceito de recursão pode referir que o conceito de funções de ordem superior oferece uma abordagem alternativa a problemas semelhantes)
  • Compromissos assumidos para facilitar a aprendizagem ou para acomodar o ambiente do Exercism, por exemplo, várias classes num único ficheiro
  • Funcionalidades semelhantes com as quais o conceito pode ser confundido
  • Características de desempenho e utilização de memória, quando forem uma consideração comum nessa linguagem
  • Não faças referência a um exercício no texto, porque este ficheiro é apresentado fora do contexto de um exercício.

Não é objetivo do ficheiro about.md fornecer um conjunto completo de informação sobre o conceito. A título de exemplo, imagina uma linguagem que tem funcionalidades antigas que os programadores experientes (e talvez até a documentação ou as especificações oficiais) recomendam que já não sejam usadas. Fornecer detalhes sobre essas funcionalidades estaria fora do âmbito do ficheiro about.md, porque não são relevantes para atingir fluência. No entanto, os maintainers podem optar por acrescentar um pequeno bloco para reconhecer os padrões antigos, caso um estudante os possa encontrar com frequência no mundo real. Ainda assim, esse bloco deve ser assinalado como tal.

O ficheiro about.md DEVE ter uma estrutura clara, sobretudo quando contém muita informação. No futuro, haverá também suporte para marcar partes como "tópicos avançados", de modo a destacá-las para os estudantes interessados sem sobrecarregar os restantes.

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.

Ficheiro: introduction.md

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

Presença: obrigatório

Este ficheiro é mostrado se o estudante ainda não tiver concluído o exercício de conceito correspondente. Deve fornecer uma breve introdução ao conceito.

  • Deve incluir-se apenas a informação necessária para compreender os fundamentos do conceito. A informação extra deve ficar para o documento about.md.
  • As ligações devem ser usadas com moderação, se é que são usadas. Embora uma ligação que explique um tópico complexo como a recursão possa ser útil, na maioria dos conceitos as ligações dão mais informação do que a necessária, por isso o objetivo deve ser explicar as coisas de forma concisa no próprio texto.
  • Devem usar-se termos técnicos corretos, para que o estudante possa procurar mais informação com facilidade.
  • Os exemplos de código só devem ser usados para introduzir sintaxe nova (o estudante não deve precisar de procurar exemplos de sintaxe na internet). Nos restantes casos, apresenta descrições ou ligações em vez de código.
  • Não faças referência a um exercício no texto, porque este ficheiro é apresentado 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 ligações úteis com mais leitura ou informação sobre um conceito.

Presença: obrigatório

Podem ser documentação oficial, um bom tutorial, etc. Estas ligações não substituem as ligações mais contextuais dentro do ficheiro about.md de um conceito; servem antes para dar ao estudante um conjunto rápido de pontos de referência gerais.

Cada ligação tem de conter os seguintes campos:

  • url: o URL para onde aponta.
  • description: uma descrição da ligação, que é mostrada como texto da ligação.

As ligações podem também ter, opcionalmente, um campo icon_url, que serve para personalizar o ícone mostrado quando a ligação é apresentada. Se não for especificado, o ícone é, por omissã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"
  }
]

Ficheiro: .meta/config.json

Objetivo: conter informações de metadados sobre o conceito.

Presença: obrigatório

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

  • authors: o(s) nome(s) de utilizador do GitHub do(s) autor(es) do conceito (obrigatório)
    • Inclui os revisores se as suas revisões alterarem substancialmente o conceito (ao ponto de parecer que "chegaram lá juntos")
  • contributors: o(s) nome(s) de utilizador do GitHub do(s) contribuidor(es) do conceito (opcional)
    • Inclui os revisores se as suas revisões forem significativas, acionáveis ou já aplicadas.
  • blurb: uma descrição breve deste conceito. O comprimento tem de ser <= 350. Não é suportado Markdown (obrigatório)

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

Exemplo

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

Tem em atenção que:

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