Concetti

I concetti sono le cose che un programmatore deve capire per padroneggiare un linguaggio. I concetti vengono insegnati dagli esercizi concettuali e servono da prerequisiti sia per gli esercizi concettuali sia per quelli pratici. I concetti vengono inseriti in una mappa concettuale quando vengono mostrati allo studente.

Metadati

I metadati di un concetto sono definiti nella chiave concepts del file config.json. I metadati definiscono l'UUID, lo slug e altro ancora del concetto.

Esempio

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

File

Ogni concetto ha una propria cartella all'interno della cartella concepts della traccia. Il nome della cartella del concetto deve corrispondere alla proprietà slug del concetto, come definita nel file config.json.

Un concetto ha due tipi di file:

File di documentazione

Questi file vengono mostrati allo studente per aiutarlo a capire il concetto.

  • about.md: fornisce informazioni sul concetto a uno studente che ha completato l'esercizio concettuale corrispondente, per imparare e per consultarle in seguito (obbligatorio)
  • introduction.md: fornisce una breve introduzione a uno studente che non ha ancora completato l'esercizio concettuale corrispondente (obbligatorio)
  • links.json: fornisce link utili con approfondimenti o informazioni su un concetto (obbligatorio)

File di metadati

Questi file non vengono mostrati allo studente, ma servono a definire i metadati del concetto.

  • .meta/config.json: contiene le meta-informazioni sul concetto (obbligatorio)

Esempio

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

File: about.md

Scopo: fornisce informazioni più dettagliate sul concetto a uno studente che ha completato l'esercizio concettuale corrispondente, per imparare e per consultarle in seguito.

Presenza: Obbligatorio

Dopo aver completato l'esercizio concettuale corrispondente (noto anche come «imparare» un concetto), la pagina del concetto mostra il contenuto del file about.md invece di quello del file introduction.md. Il file about.md dovrebbe fornire agli studenti informazioni complete su ciò che devono sapere per padroneggiare il concetto. Come minimo, questo file dovrebbe contenere tutte le informazioni introdotte nel documento introduction.md del concetto.

Se il concetto introduce una nuova sintassi, vanno inclusi degli esempi di sintassi. Lo studente non dovrebbe dover seguire molti link per acquisire le conoscenze che il file cerca di trasmettere. Il file about.md, invece, dovrebbe contenere informazioni sufficienti per essere comprensibile nel suo contesto.

Il file about.md non è limitato allo scope dell'esercizio concettuale corrispondente. Il contenuto può richiedere la conoscenza di altri concetti che verranno introdotti più avanti. Se vengono menzionati altri concetti, si dovrebbe rimandare alle rispettive introduzioni con un link (vedi link interni per i dettagli).

Ecco alcuni esempi di ciò che si potrebbe trattare.

  • Usi comuni di un concetto
  • Trappole comuni nell'uso di un concetto (ad esempio non considerare la sicurezza dei thread)
  • Limiti d'uso che possono cogliere di sorpresa lo sviluppatore ignaro
  • Approcci alternativi trattati in altri concetti (ad esempio il concetto di ricorsione potrebbe ricordare che il concetto Funzioni di ordine superiore offre un approccio alternativo a problemi simili)
  • Compromessi fatti per facilitare l'apprendimento o per adattarsi all'ambiente di Exercism, ad esempio più classi in un unico file
  • Funzionalità simili con cui il concetto può essere confuso
  • Caratteristiche prestazionali e uso della memoria, quando sono una considerazione comune in quel linguaggio
  • Non fare riferimento a un esercizio nel testo, perché questo file viene mostrato al di fuori del contesto di un esercizio.

Lo scopo del file about.md non è fornire una serie completa di informazioni sul concetto. Per esempio, immagina un linguaggio con alcune funzionalità più vecchie che i programmatori esperti (e forse persino la documentazione o le specifiche ufficiali) consigliano di non usare più. Entrare nei dettagli di queste funzionalità sarebbe fuori dallo scope del file about.md, perché non sono rilevanti per raggiungere la padronanza. Tuttavia, i manutentori possono scegliere di aggiungere un breve blocco per riconoscere gli standard più vecchi, se è probabile che uno studente li incontri spesso in giro. In ogni caso, questo blocco dovrebbe essere contrassegnato come tale.

Il file about.md DEVE essere strutturato in modo chiaro, soprattutto quando contiene molte informazioni. In futuro sarà anche possibile contrassegnare alcune parti come «argomenti avanzati», per segnalarle agli studenti interessati senza sovraccaricare gli altri.

Esempio

# 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.

File: introduction.md

Scopo: fornisce una breve introduzione a uno studente che non ha ancora completato l'esercizio concettuale corrispondente.

Presenza: Obbligatorio

Questo file viene mostrato se uno studente non ha ancora completato l'esercizio concettuale corrispondente. Dovrebbe fornire una breve introduzione al concetto.

  • Vanno fornite solo le informazioni necessarie per capire i fondamenti del concetto. Le informazioni extra vanno lasciate al documento about.md.
  • I link vanno usati con parsimonia, se non addirittura evitati. Un link che spiega un argomento complesso come la ricorsione può essere utile, ma per la maggior parte dei concetti i link forniranno più informazioni del necessario: l'obiettivo dovrebbe essere spiegare le cose in modo conciso, direttamente nel testo.
  • Vanno usati i termini tecnici corretti, così lo studente può cercare facilmente ulteriori informazioni.
  • Gli esempi di codice vanno usati solo per introdurre nuova sintassi (gli studenti non dovrebbero aver bisogno di cercare esempi di sintassi sul web). Negli altri casi fornisci descrizioni o link invece del codice.
  • Non fare riferimento a un esercizio nel testo, perché questo file viene mostrato al di fuori del contesto di un esercizio.

Esempio

# 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;
```

Scopo: fornisce link utili con approfondimenti o informazioni su un concetto.

Presenza: Obbligatorio

Possono essere documentazione ufficiale, un buon tutorial, ecc. Questi link non sostituiscono i link più contestuali presenti nel file about.md di un concetto, ma offrono allo studente un rapido insieme di punti di riferimento generali.

Ogni link deve contenere i seguenti campi:

  • url: l'URL a cui punta il link.
  • description: una descrizione del link, che viene mostrata come testo del link.

I link possono anche avere un campo facoltativo icon_url, che si può usare per personalizzare l'icona mostrata quando il link viene visualizzato. Se non viene specificata, l'icona predefinita è la 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"
  }
]

File: .meta/config.json

Scopo: contiene le meta-informazioni sul concetto.

Presenza: Obbligatorio

Questo file contiene le meta-informazioni sul concetto:

  • authors: il nome utente o i nomi utente GitHub dell'autore o degli autori del concetto (obbligatorio)
    • Include anche i revisori se le loro revisioni cambiano sostanzialmente il concetto (al punto da sembrare «ci siete arrivati insieme»)
  • contributors: il nome utente o i nomi utente GitHub dei contributori del concetto (facoltativo)
    • Include anche i revisori se le loro revisioni sono significative, attuabili o già attuate.
  • blurb: una breve descrizione di questo concetto. La sua lunghezza deve essere <= 350. Markdown non è supportato (obbligatorio)

Se qualcuno è sia autore che contributore, elencalo solo come autore.

Esempio

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

Nota che:

  • L'ordine degli autori e dei contributori non è significativo e non ha alcun significato.