Η διεπαφή του αναλυτή

Όλες οι αλληλεπιδράσεις με τον ιστότοπο του Exercism γίνονται αυτόματα. Οι αναλυτές έχουν μία μόνο ευθύνη: να παίρνουν μια λύση και να επιστρέφουν μια κατάσταση και τυχόν μηνύματα.

Εκτέλεση

  • Ένας αναλυτής θα πρέπει να παρέχει ένα εκτελέσιμο script. Μπορείς να βρεις περισσότερες πληροφορίες στο αρχείο docker.md.
  • Το script θα δεχτεί τρεις παραμέτρους:
    • Το slug της άσκησης (π.χ. two-fer).
    • Μια διαδρομή προς έναν κατάλογο που περιέχει τα υποβληθέντα αρχεία (με κάθετο στο τέλος).
    • Μια διαδρομή προς έναν κατάλογο εξόδου (με κάθετο στο τέλος). Αυτός ο κατάλογος είναι εγγράψιμος.
  • Το script πρέπει να γράψει ένα αρχείο analysis.json στον κατάλογο εξόδου.
  • Το script θα πρέπει να γράψει ένα αρχείο tags.json στον κατάλογο εξόδου.

Επιτρεπόμενος χρόνος εκτέλεσης

Ο αναλυτής παίρνει το 100% των πόρων του μηχανήματος για ένα παράθυρο 20 δευτερολέπτων ανά λύση. Μετά τα 20 δευτερόλεπτα, η διεργασία σταματά και αναφέρει υπέρβαση χρόνου.

Note

Σου συνιστούμε ανεπιφύλακτα να ακολουθήσεις το έγγραφο Βέλτιστων Πρακτικών Απόδοσης για να μειώσεις την πιθανότητα υπερβάσεων χρόνου.

Μορφή εξόδου

analysis.json

Το αρχείο analysis.json πρέπει να έχει την ακόλουθη δομή:

{
  "summary": "This solution looks good but has a few points to address",
  "comments": [
    {
      "comment": "ruby.general.some_parameterised_message",
      "params": { "foo": "param1", "bar": "param2" },
      "type": "essential"
    },
    {
      "comment": "ruby.general.some_unparameterised_message",
      "params": {},
      "type": "actionable"
    },
    {
      "comment": "ruby.general.some_unparameterised_message"
    },
    "ruby.general.some_unparameterised_message"
  ]
}

summary (προαιρετικό)

Το πεδίο summary είναι ένα πεδίο κειμένου (όχι markdown) που συνοψίζει την έξοδο. Μπορεί να λέει κάτι σαν "Η λύση σου είναι σχεδόν έτοιμη, μένουν μόνο δύο μικρές αλλαγές που μπορείς να κάνεις." ή "Ο κώδικας δουλεύει εξαιρετικά, αλλά χρειάζεται να γίνει λίγο linting.". Αυτή η σύνοψη εμφανίζεται στον ιστότοπο πάνω από τα σχόλια.

comments

Το πεδίο comments είναι ένας πίνακας σχολίων που παραπέμπουν σε έγγραφα Markdown στο exercism/website-copy (δες το Συγγραφή σχολίων αναλυτή για περισσότερες πληροφορίες). Κάθε τιμή στον πίνακα είναι είτε μια συμβολοσειρά-δείκτης είτε ένα αντικείμενο JSON με την ακόλουθη μορφή:

comment

Η συμβολοσειρά-δείκτης προς ένα αρχείο στο website-copy.

params (προαιρετικό)

Ένα αντικείμενο JSON που περιέχει τυχόν παραμέτρους που πρέπει να παρεμβληθούν κατά την απόδοση. Για παράδειγμα, στο αρχείο markdown, θα μπορούσες να γράψεις Try %{variable_name} += 1 instead, και μετά να ορίσεις το params σε { "variable_name": "foo"} ώστε να αντικαταστήσεις το %{variable_name} με την πραγματική μεταβλητή που χρησιμοποίησε ο μαθητής.

Όταν χρησιμοποιείς αρχεία με παραμέτρους, φρόντισε να βάζεις χαρακτήρα διαφυγής σε κάθε χρήση του %, τοποθετώντας άλλο ένα % μπροστά του. π.χ. Try aim aim for 100%% of the tests passing.

type (προαιρετικό)

Οι παρακάτω τιμές για το type είναι έγκυρες:

  • essential: Θα μπλοκάρουμε προσωρινά τους μαθητές μέχρι να ασχοληθούν με αυτό το σχόλιο
  • actionable: Κάθε σχόλιο που δίνει μια συγκεκριμένη οδηγία σε έναν χρήστη για να βελτιώσει τη λύση του
  • informative: Σχόλια που δίνουν πληροφορίες, αλλά δεν περιμένουν απαραίτητα από τους μαθητές να τις χρησιμοποιήσουν. Για παράδειγμα, στη Ruby, αν κάποιος χρησιμοποιεί Συνένωση Συμβολοσειρών στο TwoFer, του μιλάμε και για τη Μορφοποίηση Συμβολοσειρών, αλλά δεν υπονοούμε ότι είναι καλύτερη επιλογή.
  • celebratory: Σχόλια που λένε στους χρήστες ότι έκαναν κάτι σωστά, είτε ως γενικό σχόλιο για τη λύση είτε για μια τεχνική.

Τα σχόλια χωρίς πεδίο type έχουν ως προεπιλεγμένη τιμή το informative .

Αυτή τη στιγμή στον ιστότοπο, κάνουμε προσωρινό μπλοκάρισμα στα essential σχόλια, ενθαρρύνουμε τους μαθητές να ολοκληρώσουν τα actionable σχόλια πριν σημειώσουν ως ολοκληρωμένες τις Ασκήσεις Practice (αλλά όχι τις Ασκήσεις Concept), αλλά δεν προτείνουμε καμία ενέργεια για τα informative ή celebratory. Ωστόσο, στο μέλλον μπορεί να επιλέξουμε να προσθέσουμε emoji ή ενδείξεις σε άλλους τύπους, ή να τους ομαδοποιήσουμε ξεχωριστά.

tags.json

Το αρχείο tags.json πρέπει να έχει την ακόλουθη δομή:

{
  "tags": [
    "construct:list",
    "paradigm:functional",
    "technique:higher-order-functions",
    "uses:List.unfold"
  ]
}

tags

Το πεδίο tags είναι ένας πίνακας συμβολοσειρών. Κάθε ετικέτα έχει τη μορφή: "<category>:<thing>".

Μερικά παραδείγματα είναι:

  • "paradigm:functional"
  • "technique:recursion"
  • "construct:bitwise-and"
  • "uses:DateTime.add_seconds"

Οι ετικέτες μπορούν να χρησιμοποιηθούν για να προσδιορίσουν ποιες δομές/τεχνικές/παραδείγματα χρησιμοποιεί μια λύση.

Για περισσότερες πληροφορίες, δες το Προσθήκη ετικετών σε λύσεις.

Αποσφαλμάτωση

Τα περιεχόμενα των stdout και stderr από κάθε εκτέλεση θα διατηρούνται σε αρχεία που μπορείς να δεις αργότερα.

Μπορείς να γράψεις ένα αρχείο analysis.out που περιέχει πληροφορίες αποσφαλμάτωσης που θέλεις να δεις αργότερα.

Περαιτέρω ανάγνωση

Πριν φτιάξεις έναν αναλυτή, διάβασε τις Οδηγίες για τους αναλυτές.