Fogalmak

A fogalmak azok a dolgok, amelyeket egy programozónak meg kell értenie ahhoz, hogy folyékonyan használjon egy nyelvet. A fogalmakat tanulófeladatok tanítják, és előfeltételként szolgálnak a tanuló- és gyakorlófeladatokhoz. A fogalmak egy fogalomtérképre kerülnek, amikor megjelennek a tanulónak.

Metaadatok

A fogalmak metaadatait a config.json fájl concepts kulcsa definiálja. A metaadatok határozzák meg a fogalom UUID-ját, slugját és egyebeket.

Példa

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

Fájlok

Minden fogalomnak saját könyvtára van a kurzus concepts könyvtárán belül. A fogalom könyvtárának nevének meg kell egyeznie a fogalom slug tulajdonságával, ahogyan az a config.json fájlban szerepel.

Egy fogalomnak kétféle fájlja van:

Dokumentációs fájlok

Ezeket a fájlokat a tanulónak jelenítjük meg, hogy segítsenek megérteni a fogalmat.

  • about.md: információt nyújt a fogalomról annak a tanulónak, aki már teljesítette a hozzá tartozó tanulófeladatot, hogy tanulhasson belőle és később visszakereshesse (kötelező)
  • introduction.md: rövid bevezetést nyújt annak a tanulónak, aki még nem teljesítette a hozzá tartozó tanulófeladatot (kötelező)
  • links.json: hasznos linkeket nyújt, amelyek további olvasnivalót vagy információt kínálnak egy fogalomról (kötelező)

Metaadatfájlok

Ezeket a fájlokat nem jelenítjük meg a tanulónak, hanem a fogalom metaadatainak meghatározására használjuk.

  • .meta/config.json: a fogalomra vonatkozó metainformációkat tartalmazza (kötelező)

Példa

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

Fájl: about.md

Cél: Részletesebb információt nyújt a fogalomról annak a tanulónak, aki már teljesítette a hozzá tartozó tanulófeladatot, hogy tanulhasson belőle és később visszakereshesse.

Megléte: Kötelező

Miután a tanuló teljesítette a hozzá tartozó tanulófeladatot (ezt nevezik a fogalom „megtanulásának”), a fogalom oldala az about.md fájl tartalmát mutatja majd az introduction.md fájl helyett. Az about.md fájlnak átfogó információt kell nyújtania a tanulóknak arról, amit tudniuk kell ahhoz, hogy folyékonyan használják a fogalmat. Ez a fájl legalább annyi információt tartalmazzon, mint amennyi a fogalom introduction.md dokumentumában szerepel.

Ha a fogalom új szintaxist vezet be, a szintaxisra példákat is szerepeltetni kell. A tanulónak nem kellene rengeteg linket követnie ahhoz, hogy megszerezze azt a tudást, amit a fájl közvetíteni próbál. Ehelyett az about.md annyi információt tartalmazzon, hogy a saját kontextusában érthető legyen.

Az about.md fájl nem korlátozódik a hozzá tartozó tanulófeladat hatókörére. A tartalom megkövetelheti olyan más fogalmak ismeretét, amelyeket csak később vezetünk be. Ha más fogalmakat említünk, azok bevezetőire hivatkozni kell (részletekért lásd: belső hivatkozások).

Íme néhány példa arra, hogy mi kerülhet bele.

  • Egy fogalom népszerű felhasználási módjai
  • Egy fogalom használatának gyakori buktatói (pl. a szálbiztonság figyelmen kívül hagyása)
  • Olyan használati korlátok, amelyekbe a gyanútlan fejlesztő könnyen belefuthat
  • Más fogalmaknál tárgyalt alternatív megközelítések (pl. a rekurzió fogalma utalhat arra, hogy a magasabb rendű függvények fogalma alternatív megközelítést kínál hasonló problémákra)
  • A könnyebb tanulás vagy az Exercism környezetéhez való alkalmazkodás érdekében tett kompromisszumok, pl. több osztály egyetlen fájlban
  • Hasonló nyelvi elemek, amelyekkel a fogalom könnyen összekeverhető
  • A teljesítmény jellemzői és a memóriahasználat, ha ezek az adott nyelvben gyakori szempontot jelentenek
  • A szövegben ne hivatkozz feladatra, mert ez a fájl a feladat kontextusán kívül jelenik meg.

Nem az a célja az about.md fájlnak, hogy teljes körű információt nyújtson a fogalomról. Képzelj el például egy nyelvet, amelynek vannak régebbi nyelvi elemei, amelyeket a tapasztalt programozók (és talán még a hivatalos dokumentációk vagy specifikációk is) már nem ajánlanak használatra. Az ilyen nyelvi elemek részletes bemutatása kívül esne az about.md fájl hatókörén, mert nem szükségesek a folyékonyság eléréséhez. A karbantartók azonban dönthetnek úgy, hogy hozzáadnak egy rövid bekezdést a régi szabványok elismerésére, ha a tanuló nagy valószínűséggel találkozhat velük a való életben. Ezt a bekezdést azonban meg kell jelölni ilyenként.

Az about.md fájlnak egyértelműen strukturáltnak KELL lennie, különösen akkor, ha sok információt tartalmaz. A jövőben lehetőség lesz arra is, hogy egyes részeket „haladó témákként” jelöljünk meg, hogy felhívjuk rájuk az érdeklődő tanulók figyelmét anélkül, hogy a többieket túlterhelnénk.

Példa

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

Fájl: introduction.md

Cél: Rövid bevezetést nyújt annak a tanulónak, aki még nem teljesítette a hozzá tartozó tanulófeladatot.

Megléte: Kötelező

Ez a fájl akkor jelenik meg, ha a tanuló még nem teljesítette a hozzá tartozó tanulófeladatot. Rövid bevezetést kell nyújtania a fogalomba.

  • Csak azt az információt tartalmazza, amely a fogalom alapjainak megértéséhez szükséges. A felesleges információkat hagyd meg az about.md dokumentumnak.
  • A linkeket mértékkel használd, ha egyáltalán. Bár egy olyan link, amely egy összetett témát, például a rekurziót magyarázza, hasznos lehet, a legtöbb fogalomnál a linkek a szükségesnél több információt adnak, ezért arra törekedj, hogy a dolgokat tömören, helyben magyarázd el.
  • A megfelelő szakmai kifejezéseket használd, hogy a tanuló könnyen rákereshessen a további információra.
  • Kódpéldákat csak új szintaxis bemutatására használj (a tanulóknak nem kell a weben szintaxis példák után kutatniuk). Más esetekben kód helyett inkább leírásokat vagy linkeket adj.
  • A szövegben ne hivatkozz feladatra, mert ez a fájl a feladat kontextusán kívül jelenik meg.

Példa

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

Cél: Hasznos linkek nyújtása, amelyek további olvasnivalót vagy információt kínálnak egy fogalomról.

Megléte: Kötelező

Lehetnek hivatalos dokumentációk, egy remek útmutató, és így tovább. Ezek a linkek nem helyettesítik a fogalom about.md fájljában található, kontextusba ágyazottabb linkeket, hanem gyors, átfogó viszonyítási pontokat kínálnak a tanulónak.

Minden linknek a következő mezőket kell tartalmaznia:

  • url: az URL, amelyre mutat.
  • description: a link leírása, amely a hivatkozás szövegeként jelenik meg.

A linkeknek opcionálisan lehet icon_url mezőjük is, amellyel testre szabható a link megjelenítésekor látható ikon. Ha nincs megadva, az ikon alapértelmezés szerint a 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"
  }
]

Fájl: .meta/config.json

Cél: A fogalomra vonatkozó metainformációkat tartalmazza.

Megléte: Kötelező

Ez a fájl a fogalomra vonatkozó metainformációkat tartalmazza:

  • authors: a fogalom szerzőjének (szerzőinek) GitHub-felhasználóneve(i) (kötelező)
    • Beleértve azokat a bírálókat is, akiknek a bírálata érdemben megváltoztatta a fogalmat (annyira, hogy úgy érzed, „együtt jutottatok el idáig”)
  • contributors: a fogalom közreműködőinek GitHub-felhasználóneve(i) (opcionális)
    • Beleértve azokat a bírálókat is, akiknek a bírálata érdemi, hasznosítható vagy hasznosított.
  • blurb: a fogalom rövid leírása. A hossza legfeljebb 350 lehet. A Markdown nem támogatott (kötelező)

Ha valaki egyszerre szerző és közreműködő, csak szerzőként soroljuk fel.

Példa

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

Vedd figyelembe, hogy:

  • A szerzők és közreműködők sorrendje nem számít, és nincs jelentése.