Προσθήκη άσκησης εξάσκησης

Αυτό το κείμενο εξηγεί πώς να προσθέσεις μια νέα άσκηση πρακτικής.

Επιλογή άσκησης

Ο πιο απλός τρόπος για να δεις ποιες ασκήσεις πρακτικής δεν έχουν υλοποιηθεί ακόμη είναι να πας στη σελίδα build της διαδρομής (π.χ. https://exercism.org/tracks/csharp/build) και να κοιτάξεις την ενότητα "Ασκήσεις Πρακτικής".

Caution

Τα δεδομένα στη σελίδα build ενημερώνονται μία φορά την ημέρα.

Δημιουργία σκελετού άσκησης

Μπορείς να δημιουργήσεις γρήγορα τον σκελετό μιας νέας άσκησης πρακτικής τρέχοντας το script bin/add-practice-exercise (πηγή) από τον ριζικό κατάλογο της διαδρομής:

bin/add-practice-exercise <exercise-slug>

Προαιρετικά, μπορείς να ορίσεις και τη δυσκολία της άσκησης (με το -d) ή/και το όνομα χρήστη του συγγραφέα στο GitHub (με το -a):

bin/add-practice-exercise -d 3 -a foobar <exercise-slug>
Note

Αν δουλεύεις σε ένα αποθετήριο διαδρομής που δεν έχει αυτό το αρχείο, μη διστάσεις να το αντιγράψεις στο αποθετήριό σου χρησιμοποιώντας τον σύνδεσμο πηγής παραπάνω.

Υλοποίηση άσκησης

Μόλις δημιουργηθούν τα αρχεία του σκελετού, θα πρέπει να κάνεις τα εξής:

  • Πρόσθεσε tests στο αρχείο tests
  • Πρόσθεσε ένα παράδειγμα υλοποίησης
  • Όρισε το περιεχόμενο του αρχείου stub
  • Μέσα στο αρχείο .meta/config.json της άσκησης:
    • Πρόσθεσε το όνομα χρήστη στο GitHub των συγγραφέων της άσκησης στο κλειδί authors
  • Μέσα στο αρχείο config.json της διαδρομής:
    • Έλεγξε/ενημέρωσε τη δυσκολία της άσκησης
    • Πρόσθεσε έννοιες στο κλειδί practices (απαιτείται μόνο όταν η διαδρομή έχει ασκήσεις εννοιών)
    • Πρόσθεσε έννοιες στο κλειδί prerequisites (απαιτείται μόνο όταν η διαδρομή έχει ασκήσεις εννοιών)

Προσθήκη tests

Βασικό κομμάτι της προσθήκης μιας άσκησης είναι η προσθήκη tests. Σε γενικές γραμμές, υπάρχουν δύο επιλογές όταν προσθέτεις tests για μια άσκηση πρακτικής:

  1. Να υλοποιήσεις τα tests από το μηδέν, χρησιμοποιώντας τα test cases από το αρχείο canonical-data.json της άσκησης, όπως αυτά βρίσκονται στο αποθετήριο problem-specifications.
  2. Να μεταφέρεις τα tests από την υλοποίηση μιας άλλης διαδρομής (συμβουλή: πήγαινε στο https://exercism.org/exercises/<slug> για να δεις συνοπτικά ποιες διαδρομές έχουν υλοποιήσει μια συγκεκριμένη άσκηση).

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

Note

Κάποιες διαδρομές χρησιμοποιούν έναν test generator για να (ξανα)δημιουργούν αυτόματα τα αρχεία tests μιας άσκησης. Έλεγξε την τεκμηρίωση της διαδρομής για να δεις αν υπάρχει test generator και, αν υπάρχει, πώς να τον χρησιμοποιήσεις.

Προσθήκη παραδείγματος υλοποίησης

Για να διασφαλιστεί ότι είναι δυνατόν να γραφτεί κώδικας που περνάει τα tests, πρέπει να προστεθεί ένα παράδειγμα υλοποίησης.

Note

Ο κώδικας δε χρειάζεται να είναι ιδιωματικός, αρκεί να περνάει τα tests.

Μπορείς να επαληθεύσεις ότι το παράδειγμα υλοποίησης περνάει όλα τα tests τρέχοντας το script bin/verify-exercises (πηγή) από τον ριζικό κατάλογο της διαδρομής:

bin/verify-exercises <exercise-slug>

Χρησιμοποίησε την έξοδο για να επαληθεύσεις ότι το παράδειγμα υλοποίησης περνάει όλα τα tests.

Note

Αν δουλεύεις σε ένα αποθετήριο διαδρομής που δεν έχει αυτό το αρχείο, μη διστάσεις να το αντιγράψεις στο αποθετήριό σου χρησιμοποιώντας τον σύνδεσμο πηγής παραπάνω.

Advanced

Στο παρασκήνιο, το script bin/verify-exercises κάνει αρκετά πράγματα:

  • Αντιγράφει την άσκηση σε έναν προσωρινό κατάλογο
  • Αντικαθιστά τα αρχεία stub με τα αρχεία του παραδείγματος υλοποίησης
  • Αν το αρχείο tests έχει tests που έχουν παραλειφθεί, αυτά θα ενεργοποιηθούν ξανά
  • Εκτελεί τα tests

Προσθήκη αρχείων stub

Τα αρχεία του stub παρέχουν ένα σημείο εκκίνησης για τους μαθητές.

Προτείνουμε τα αρχεία stub να περιέχουν τον ελάχιστο δυνατό κώδικα, ώστε:

  • Ο μαθητής να μπορεί να αρχίσει αμέσως να υλοποιεί τη λογική για να περάσει τα tests
  • Ο μαθητής να μην έρχεται αντιμέτωπος με "περίεργα" συντακτικά λάθη

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

Παραδείγματα

Python:

def two_fer(name):
    pass

Kotlin:

fun twofer(name: String): String {
    TODO("Implement the function to complete the task")
}

Έλεγχος lint της άσκησης

Το τελευταίο βήμα είναι να τρέξεις τον linter για να ελέγξεις αν τα αρχεία (ρυθμίσεων) της διαδρομής είναι σωστά δομημένα, και συντακτικά και σημασιολογικά.

Πρώτα, βεβαιώσου ότι έχεις την τελευταία έκδοση του configlet τρέχοντας:

bin/fetch-configlet

Στη συνέχεια, τρέξε τον linter με:

bin/configlet lint

Χρησιμοποίησε την έξοδο για να βεβαιωθείς ότι όλα είναι εντάξει.

Υποβολή Pull Request

Μόλις όλα είναι εντάξει, μπορείς να υποβάλεις ένα Pull Request στο αποθετήριο της διαδρομής.

Πριν υποβάλεις, διάβασε τον Οδηγό Pull Request για Συνεισφέροντες και τον Οδηγό Pull Request.

Βεβαιώσου ότι η περιγραφή του PR αναφέρει την άσκηση που προστίθεται.