개념

개념은 프로그래머가 어떤 언어에 유창해지려면 이해해야 하는 것들이에요. 개념은 개념 연습 문제를 통해 가르치고, 개념 연습 문제와 실습 문제의 선수 조건으로 사용해요. 개념은 학생에게 표시될 때 개념 지도 위에 배치돼요.

메타데이터

개념 메타데이터는 config.json 파일의 concepts 키에 정의해요. 이 메타데이터는 개념의 UUID, slug 등을 정의해요.

예시

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

파일

각 개념은 트랙의 concepts 디렉터리 안에 각자의 디렉터리를 가져요. 개념 디렉터리의 이름은 config.json 파일에 정의된 개념의 slug 속성과 일치해야 해요.

개념에는 두 종류의 파일이 있어요:

문서 파일

이 파일들은 개념을 설명하는 데 도움이 되도록 학생에게 보여 줘요.

  • about.md: 해당 개념 연습 문제를 완료한 학생이 학습하고 다시 참고할 수 있도록 개념에 대한 정보를 제공해요 (필수)
  • introduction.md: 아직 해당 개념 연습 문제를 완료하지 않은 학생에게 개념을 간단히 소개해요 (필수)
  • links.json: 개념에 대해 더 읽어 볼 자료나 정보를 제공하는 유용한 링크를 담아요 (필수)

메타데이터 파일

이 파일들은 학생에게 보여 주지 않고, 개념의 메타데이터를 정의하는 데 사용해요.

  • .meta/config.json: 개념에 대한 메타 정보를 담고 있어요 (필수)

예시

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

파일: about.md

목적: 해당 개념 연습 문제를 완료한 학생이 학습하고 다시 참고할 수 있도록 개념에 대해 더 자세한 정보를 제공해요.

존재 여부: 필수

해당 개념 연습 문제를 완료하면(이를 개념을 "학습했다"고도 해요), 개념 페이지에는 introduction.md 파일 대신 about.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."
}

참고로:

  • 작성자와 기여자의 순서는 중요하지 않으며 아무런 의미도 없어요.