Концепції

Концепції - це те, що програміст має розуміти, аби вільно володіти мовою. Концепції викладають у концептуальних вправах, і вони слугують передумовами для концептуальних і практичних вправ. Коли концепції показують студентові, їх розміщують на карті концепцій.

Метадані

Метадані концепції визначено в ключі concepts у файлі config.json. Метадані визначають UUID концепції, її slug та інше.

Приклад

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

Файли

Кожна концепція має власний каталог усередині каталогу concepts треку. Назва каталогу концепції має збігатися з властивістю slug концепції, визначеною у файлі config.json.

Концепція містить два типи файлів:

Файли документації

Ці файли показують студентові, щоб допомогти пояснити концепцію.

  • about.md: подає інформацію про концепцію для студента, який уже виконав відповідну концептуальну вправу, щоб він міг навчатися за нею і повертатися до неї (обовʼязковий)
  • introduction.md: коротко знайомить із концепцією студента, який ще не виконав відповідну концептуальну вправу (обовʼязковий)
  • links.json: подає корисні посилання з додатковими матеріалами чи інформацією про концепцію (обовʼязковий)

Файли метаданих

Ці файли не показують студентові, вони визначають метадані концепції.

  • .meta/config.json: містить метаінформацію про концепцію (обовʼязковий)

Приклад

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

Файл: about.md

Призначення: надати докладнішу інформацію про концепцію студентові, який уже виконав відповідну концептуальну вправу, щоб він міг навчатися за нею і повертатися до неї.

Наявність: обовʼязковий

Після виконання відповідної концептуальної вправи (інакше кажучи, «вивчення» концепції) сторінка концепції показуватиме вміст файлу about.md замість файлу introduction.md. Файл about.md має давати студентам вичерпну інформацію про те, що потрібно знати, щоб вільно володіти концепцією. Як мінімум, цей файл має містити всю інформацію, яку подано в документі introduction.md концепції.

Якщо концепція вводить новий синтаксис, слід додати зразки синтаксису. Студентові не потрібно переходити за багатьма посиланнями, щоб здобути знання, які прагне передати цей файл. Замість цього файл about.md має містити достатньо інформації, щоб його можна було зрозуміти в його контексті.

Файл about.md не обмежується обсягом відповідної концептуальної вправи. Його вміст може вимагати знання інших концепцій, які буде введено пізніше. Якщо згадано інші концепції, слід посилатися на відповідні вступи до них (докладніше див. внутрішні посилання).

Ось кілька прикладів того, що можна висвітлити.

  • Популярні способи використання концепції
  • Поширені пастки у використанні концепції (наприклад, нехтування потокобезпечністю)
  • Обмеження щодо використання, які можуть заскочити необачного розробника
  • Альтернативні підходи, розглянуті в інших концепціях (наприклад, концепція рекурсії може згадувати, що концепція функцій вищого порядку пропонує альтернативний підхід до схожих задач)
  • Компроміси, зроблені для полегшення навчання або заради пристосування до середовища Exercism, як-от кілька класів в одному файлі
  • Схожі можливості, з якими концепцію можна сплутати
  • Характеристики швидкодії та використання памʼяті, якщо це зазвичай важливо в цій мові
  • Не варто згадувати вправу в тексті, адже цей файл показують поза контекстом вправи.

Мета файлу about.md не в тому, щоб подати повний набір інформації про концепцію. Наприклад, уявімо мову, у якій є застарілі можливості, щодо яких досвідчені програмісти (а можливо, й офіційна документація чи специфікації) радять більше їх не використовувати. Деталі про такі можливості були б поза межами файлу about.md, бо вони не потрібні, щоб досягти вільного володіння. Однак супровідники можуть додати короткий блок, щоб згадати старі стандарти, якщо студент часто натраплятиме на них у реальному коді. Однак такий блок слід відповідно позначити.

Файл about.md ПОВИНЕН мати чітку структуру, особливо якщо він містить багато інформації. У майбутньому також зʼявиться підтримка позначення частин як «поглиблених тем», щоб вказувати на них зацікавленим студентам, не перевантажуючи інших.

Приклад

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

Файл: introduction.md

Призначення: коротко познайомити з концепцією студента, який ще не виконав відповідну концептуальну вправу.

Наявність: обовʼязковий

Цей файл показують, якщо студент ще не виконав відповідну концептуальну вправу. Він має коротко ввести в концепцію.

  • Слід подавати лише інформацію, потрібну для розуміння основ концепції. Додаткову інформацію варто залишити для документа about.md.
  • Посилання варто використовувати ощадливо, або й зовсім не використовувати. Хоча посилання, яке пояснює складну тему на кшталт рекурсії, може бути корисним, для більшості концепцій посилання дадуть більше інформації, ніж потрібно, тож метою має бути стисле пояснення прямо в тексті.
  • Слід використовувати належні технічні терміни, щоб студент міг легко знайти додаткову інформацію.
  • Приклади коду варто використовувати лише для представлення нового синтаксису (студентам не потрібно шукати приклади синтаксису в інтернеті). В інших випадках замість коду варто подавати описи або посилання.
  • Не варто згадувати вправу в тексті, адже цей файл показують поза контекстом вправи.

Приклад

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

Призначення: подати корисні посилання з додатковими матеріалами чи інформацією про концепцію.

Наявність: обовʼязковий

Це можуть бути офіційна документація, чудовий туторіал тощо. Ці посилання не замінюють контекстніших посилань у файлі about.md концепції, а дають студентові швидкий набір загальних орієнтирів.

Кожне посилання має містити такі поля:

  • url: URL-адреса, на яку веде посилання.
  • description: опис посилання, який показують як текст посилання.

Посилання також можуть мати необовʼязкове поле icon_url, яке дає змогу налаштувати іконку, що показується разом із посиланням. Якщо його не вказано, типово використовується 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"
  }
]

Файл: .meta/config.json

Призначення: містить метаінформацію про концепцію.

Наявність: обовʼязковий

Цей файл містить метаінформацію про концепцію:

  • authors: імена користувачів GitHub автора або авторів концепції (обовʼязкове)
    • Зокрема рецензентів, якщо їхні відгуки суттєво змінили концепцію (настільки, що здається, ніби «ви дійшли до цього разом»)
  • contributors: імена користувачів GitHub дописувачів концепції (необовʼязкове)
    • Зокрема рецензентів, якщо їхні відгуки змістовні, дієві або враховані.
  • blurb: короткий опис цієї концепції. Його довжина має бути <= 350. Markdown не підтримується (обовʼязкове)

Якщо людина є одночасно і автором, і дописувачем, її вказують лише як автора.

Приклад

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

Зауважмо:

  • Порядок авторів і дописувачів не має значення.