Έννοιες

Οι έννοιες είναι τα πράγματα που θα χρειαζόταν να κατανοήσει ένας προγραμματιστής για να έχει ευχέρεια σε μια γλώσσα. Οι έννοιες διδάσκονται από τις ασκήσεις έννοιας και χρησιμοποιούνται ως προαπαιτούμενα για ασκήσεις έννοιας και πρακτικής. Οι έννοιες τοποθετούνται σε έναν χάρτη εννοιών όταν εμφανίζονται στον μαθητή.

Μεταδεδομένα

Τα μεταδεδομένα μιας έννοιας ορίζονται στο κλειδί 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."
}

Σημείωσε ότι:

  • Η σειρά των συγγραφέων και των συνεισφερόντων δεν είναι σημαντική και δεν έχει κάποια σημασία.