Συγγραφή σχολίων αναλυτή

Αυτό το έγγραφο παρέχει πληροφορίες και οδηγίες για το πώς να γράφεις τα σχόλια που παράγει ο αναλυτής.

Περιεχόμενα

Τα περιεχόμενα των σχολίων αναλυτή αποθηκεύονται ως έγγραφο Markdown στο αποθετήριο exercism/website-copy. Τα σχόλια περιέχουν μια συμβολοσειρά δείκτη, με μορφή <track-slug>.<exercise-slug>.<comment-slug>, που παραπέμπει σε ένα συγκεκριμένο έγγραφο Markdown στο αποθετήριο website-copy.

Για παράδειγμα, το ruby.two-fer.string-interpolation παραπέμπει στο https://github.com/exercism/website-copy/blob/main/analyzer-comments/ruby/two-fer/string_interpolation.md.

Διατύπωση

• Απόφευγε τα περιττά, φλύαρα σχόλια. Να είσαι συνοπτικός.
• Να παρατηρείς με ουδέτερο τρόπο, αποφεύγοντας φορτισμένες και γενικευμένες δηλώσεις.
• Κάνε τη σύσταση ρητή.
• Όταν είναι δυνατόν, βάλε πρώτα τη σύσταση και μετά την εξήγηση.
• Απόφευγε το "me", το "I", το "we" κ.λπ., αφού το bot δεν είναι πρόσωπο.
• Απόφευγε το "you" και το "your code", γιατί μερικές φορές μπορεί να ακούγεται σαν να κρίνεις το άτομο και όχι τον κώδικα.
• Απόφευγε λέξεις όπως "just", "simply", "obviously", που μπορεί να ακούγονται συγκαταβατικές: αν το σχόλιο είναι απαραίτητο, τότε προφανώς δεν ήταν προφανές.
• Απόφευγε να κάνεις υποθέσεις για το τι ξέρουν και τι δεν ξέρουν οι άνθρωποι. Η μόνη εξαίρεση είναι η γνώση από βασικές ασκήσεις που έχουν ήδη ολοκληρωθεί. Απόφευγε τα "as you know", "as you remember", "as you learned", "now that we all understand x", γιατί ακόμα κι αν κάτι ειπώθηκε, το άτομο δεν το καταλαβαίνει απαραίτητα.

Κατευθύνσεις

• Στόχευσε στην ευχέρεια, όχι στην τελειότητα: ο στόχος μιας διαδρομής γλώσσας στο Exercism είναι να δώσει στους ανθρώπους έναν τρόπο να φτάσουν σε υψηλό επίπεδο ευχέρειας με χαμηλό επίπεδο τελειότητας. Στοχεύουμε στην ευχέρεια στη σύνταξη, στα ιδιώματα και στην πρότυπη βιβλιοθήκη της γλώσσας.
• Πρότεινε ιδιωματικό κώδικα όταν είναι δυνατόν, όπου ιδιωματικός είναι ο κώδικας που θα έγραφαν σχεδόν όλοι οι προγραμματιστές (όχι ερασιτέχνες) που γράφουν κώδικα σε αυτή τη γλώσσα. Αν κάνεις μια μη ιδιωματική πρόταση, ανέφερέ το και εξήγησε γιατί η πρόταση μπορεί να είναι ακόμα χρήσιμη.
• Ονόμασε τη διαφορά ανάμεσα σε αυτό που κάνει το άτομο και σε αυτό που είναι "ιδιωματικό" στη γλώσσα.
• Χρησιμοποίησε τους σωστούς όρους και την ορολογία, ώστε οι άνθρωποι να αναγνωρίζουν αυτές τις έννοιες και αλλού, αλλά και να μπορούν να τις αναζητήσουν μόνοι τους.
• Μη δίνεις τη λύση ως γενική συμβουλή για όλη την καθοδήγηση στο Exercism. Η μάθηση μένει όταν οι άνθρωποι ανακαλύπτουν μόνοι τους την απάντηση. Είναι μια εξαιρετικά συναρπαστική εμπειρία, και η συναισθηματική φόρτιση την κάνει αξέχαστη. Ωστόσο, αν η ανακάλυψη δεν πυροδοτεί ντοπαμίνη, έχει απόλυτο νόημα να δείξεις πώς μοιάζει. Για παράδειγμα, μπορεί να επιλέξουμε να προσφέρουμε μια μικρή βελτίωση σε μια εγκεκριμένη λύση, κάτι που είναι πολύ λιγότερο συναρπαστικό από το να δώσουμε σε κάποιον ένα σημείο μάθησης σε μια λύση που απορρίπτεται, και επομένως μπορεί να αξίζει ένα παράδειγμα αντί για έναν σύνδεσμο.
• Ταξινόμησε τα σχόλια κατά σειρά σημασίας, με το πρώτο σχόλιο να είναι το πιο σημαντικό και το τελευταίο το λιγότερο σημαντικό.
• Κράτησε τον αριθμό των σχολίων διαχειρίσιμο. Στόχευσε σε ένα έως τρία σχόλια ανά επανάληψη.
• Μην προσθέτεις το ίδιο σχόλιο δύο φορές σε μία ανάλυση. Η προσθήκη του ίδιου σχολίου με διαφορετικές παραμέτρους δεν θεωρείται διπλότυπο.
• Σκέψου να σχολιάζεις μόνο τη μορφοποίηση αν η μορφοποίηση ή το linting είναι αναπόσπαστο μέρος της γλώσσας. Όταν είναι δυνατόν, καθοδήγησε τους μαθητές προς εργαλεία αυτόματης μορφοποίησης ή/και παραπέμψε σε έναν επίσημο οδηγό στυλ.

Οι πρώτες λίγες ασκήσεις

Για τις πρώτες λίγες ασκήσεις μιας διαδρομής, τα παρακάτω είναι ιδιαίτερα σημαντικά:

• Κράτησέ το σχετικά σύντομο, αποφεύγοντας έναν τοίχο κειμένου ή να τους κατακλύσεις με συμβουλές. Αν έχουν μια εξαιρετική εμπειρία στην πρώτη άσκηση, θα επιστρέψουν και θα έχεις πολλές ακόμα ευκαιρίες να δώσεις ανατροφοδότηση για όλα όσα παρατήρησες.
• Μην εξηγείς υπερβολικά μια έννοια: μην μπαίνεις σε βάθος για τους μηχανισμούς που κρύβονται πίσω από τους μεταγλωττιστές και τα σχετικά. Σε αυτή την περίπτωση έχει περισσότερο να κάνει με το ότι αυτή είναι μία από τις πρώτες ασκήσεις στη διαδρομή γλώσσας, και σε αυτό το στάδιο η ανατροφοδότηση είναι πιο χρήσιμη αν είναι πιο σύντομη και πιο κατευθυντική.
• Δώσε έναν σύνδεσμο που δείχνει ακριβώς πώς εφαρμόζεται η έννοια, με τρόπο tutorial. Δηλαδή: να δείχνει πώς γίνονται τα πράγματα, όχι να συζητά το γιατί. Αυτό μπορεί να σημαίνει ότι η επίσημη τεκμηρίωση της γλώσσας δεν αρκεί, καθώς συχνά είναι αναφορά κώδικα και δεν σου δείχνει πώς να το χρησιμοποιήσεις και πώς λειτουργεί. Ωστόσο, θα πρέπει να δίνεις έναν σύνδεσμο μόνο για πιο εις βάθος εξερεύνηση. Το άτομο θα πρέπει να μπορεί να καταλάβει τι εννοείς απευθείας από την απάντηση, χωρίς να ακολουθήσει τον σύνδεσμο.

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

Στη JavaScript, ένας μαθητής έχει γράψει μια σταθερά ανώτατου επιπέδου με let.

<!-- not following these guidelines -->

As you know, everyone uses const, you shouldn't use let or var.

Αυτό το σχόλιο δεν ακολουθεί αυτές τις οδηγίες για τους εξής λόγους:

• Η ενέργεια έρχεται μετά την "εξήγηση".
• Το "As you know": δεν ξέρουμε αν ο μαθητής το ξέρει.
• Το "you shouldn't": δεν χρειάζεσαι το "you" για να κάνεις αυτή τη δήλωση.
• Το "everyone uses const": δεν είναι αλήθεια και μπορεί να κάνει τον μαθητή να νιώσει ότι έκανε κάτι τρομερά λάθος.
• Λείπει μια πραγματική εξήγηση του γιατί δίνεται η συμβουλή.

<!-- better -->

Prefer `const` and `let` over `var`. The `const` declaration stops a variable
from being accidentally reassigned, which provides safety, and reduces
cognitive load for someone reading the code. [This article](https://medium.com/javascript-scene/javascript-es6-var-let-or-const-ba58b8dcde75)
explains the difference between the three.

Στη Go, ένας μαθητής έχει δημιουργήσει ένα προσαρμοσμένο error αντί να χρησιμοποιήσει τα ενσωματωμένα:

<!-- not following these guidelines -->

I see you are creating a custom `error`. This is perfectly fine! If you did not
know about `errors.New` and `fmt.Errorf` have a look at them as they are much
simpler ways to create an error. Custom errors are helpful if you want to check
if an error is of a certain type later.

Αυτό το σχόλιο δεν ακολουθεί αυτές τις οδηγίες για τους εξής λόγους:

• Το "I see": ο αναλυτής δεν είναι πρόσωπο: απόφευγε το "I".
• Το "This is perfectly fine!": Προφανώς δεν είναι, αλλιώς η καθησυχαστική φράση δεν θα ήταν απαραίτητη. Πιθανότατα μπορεί να παραλειφθεί εντελώς· αν θέλεις να δώσεις μια γενική συμβουλή για κάτι που υπάρχει, μπορείς να πεις ακριβώς αυτό: "An alternative, equally valid way of doing x is y."
• Το "If you did not know about": Άφησε έξω αυτή την υπερβολικά φλύαρη φράση.\n

<!-- better -->

A custom `error` is typically used to provide custom behavior, or to distinguish
on type later. For simpler cases, it's more common to rely on `errors.New` or
`fmt.Errorf`. This [in-depth article](https://golangbot.com/custom-errors/) about
custom errors might be interesting.

CI

Επειδή τα σχόλια δεν βρίσκονται στο ίδιο αποθετήριο με τον αναλυτή, κάθε αναλυτής θα πρέπει να έχει CI (συνεχή ενσωμάτωση) που ελέγχει αν τα σχόλια που χρησιμοποιούνται σε αυτόν τον συγκεκριμένο αναλυτή (όσα μπορούν να γίνουν έξοδος), είναι σχόλια στο branch main του αποθετηρίου exercism/website-copy.

Τη στιγμή που γράφεται αυτό, αυτό το issue παρακολουθεί την κατάσταση οποιασδήποτε γενίκευσης αυτού του CI, αν υπάρχει.