Οδηγός στυλ του Exercism

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

Εφαρμογή

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

Συνέπεια μέσα σε μια άσκηση

Υπάρχουν όροι που έχουν πολλαπλές έγκυρες γραφές (π.χ. "lower case" εναντίον "lowercase"). Όπου δεν έχει συμφωνηθεί ένας ενιαίος στυλ μέσα σε αυτό το έγγραφο, αυτοί οι όροι πρέπει να χρησιμοποιούνται με συνέπεια μέσα σε μια άσκηση.

Εξαιρέσεις

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

Γλώσσα

Όλο το περιεχόμενο πρέπει να είναι γραμμένο σε αμερικανικά αγγλικά, τα οποία διαφέρουν από τα βρετανικά αγγλικά με πολλούς τρόπους. Στο μέλλον μπορεί να προκύψουν και άλλες μεταφράσεις, αλλά η "επίσημη" γλώσσα του Exercism είναι τα αμερικανικά αγγλικά.

Μονάδες μέτρησης

Όλες οι μονάδες μέτρησης πρέπει να είναι μονάδες SI ή παράγωγες του SI.

Συντομογραφίες, ακρωνύμια και αρκτικόλεξα

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

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

  • Ο συντομευμένος όρος είναι πιο γνωστός από τον μη συντομευμένο όρο
  • Το κείμενο θα γίνει υπερβολικά μακροσκελές χωρίς τη συντομογραφία

Όταν χρησιμοποιείς συντομογραφίες, εξήγησε πάντα τι σημαίνει ο όρος την πρώτη φορά που τον χρησιμοποιείς. Αυτό θα περιλαμβάνει συχνά, αλλά όχι πάντα, την ανάπτυξη της συντομογραφίας. Σπάνια θα αρκεί να αναπτύξεις μόνο τη συντομογραφία.

Ακολουθούν μερικά παραδείγματα κανόνων:

  • Προτίμησε το "if I recall correctly" αντί για το "IIRC"
  • Προτίμησε το "as far as I know" αντί για το "AFAIK"
  • Προτίμησε το "queue" αντί για το "FIFO" και το "stack" αντί για το "FILO"
  • Αντί να περιγράφεις μια διεπαφή ως "RESTful", περιέγραψε τις συγκεκριμένες ιδιότητές της
  • Αν πρέπει οπωσδήποτε να χρησιμοποιήσεις το "CRUD", εξήγησε ότι σημαίνει Create, Read, Update, Delete και ότι αυτές είναι οι βασικές ενέργειες σε τυπικές βάσεις δεδομένων

Και μερικά παραδείγματα καλής χρήσης:

  • "HyperText Markup Language (HTML) is the language used to describe document structure and content on the web" (αναπτύχθηκε και εξηγήθηκε)
  • "DNA, a set of chemical instructions that influence how our bodies are constructed" (Το DNA δεν αναπτύσσεται, επειδή το "deoxyribonucleic acid" είναι απίθανο να βοηθήσει στο να εξηγήσουμε τι είναι το DNA στο κοινό μας)
  • "NASA, the United States' space agency, launched the Mariner 2 space probe in..." (Το NASA δεν αναπτύσσεται, επειδή το "National Aerospace and Space Administration" είναι πολύ πιο γνωστό με το ακρωνύμιό του παρά με το πλήρες όνομά του)
  • "The Department of Motor Vehicles (DMV) is filled with sloths. That's why everything takes forever at the DMV" (Όρισε το DMV την πρώτη φορά που το χρησιμοποιείς)

Γραμματική

Κόμμα της Οξφόρδης

Χρησιμοποίησε το "κόμμα της Οξφόρδης" (γνωστό και ως σειριακό κόμμα) στις λίστες. Για παράδειγμα, αντί για "I love my parents, Lady Gaga and Humpty Dumpty", γράψε "I love my parents, Lady Gaga, and Humpty Dumpty". Μπορεί επίσης να σου αρέσει αυτή η εικόνα ως εξήγηση.

Εξαιρέσεις

Κάποιες συντομογραφίες θεωρούνται αρκετά κοινές, χρήσιμες και μη τεχνικές, ώστε έχουμε αποφασίσει να τις επιτρέπουμε:

  • e.g. ή eg
  • i.e. ή ie
  • etc. ή etc
  • docs

Οι συστολές (π.χ. "won't", "I'm", "that's") θα πρέπει να χρησιμοποιούνται με φειδώ, αν χρησιμοποιούνται καθόλου, στις περιγραφές των ασκήσεων, αλλά δεν περιορίζονται στην υπόλοιπη γλώσσα γύρω από τον ιστότοπο (π.χ. κείμενο του ιστότοπου, mentoring).

Πολλοί οδηγοί στυλ των αμερικανικών αγγλικών αναφέρουν ότι οι συντομογραφίες "i.e." και "e.g." πρέπει να ακολουθούνται από κόμμα (δείτε, π.χ., αυτό το νήμα στο StackExchange). Αυτό επιτρέπεται, αλλά δεν απαιτείται στο κείμενο του Exercism.

Επιλογή λέξεων

Μαθηματικοί όροι και τεχνική ορολογία

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

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

  • Αντί να χρησιμοποιούμε το "natural numbers", θα πρέπει να χρησιμοποιούμε το "positive whole numbers".
  • Αν θέλουμε να χρησιμοποιήσουμε τη φράση "rational numbers", πρέπει να εξηγείται στην εισαγωγή της άσκησης.
  • Αντί να χρησιμοποιείς τη λέξη range (η οποία μπορεί να έχει διαφορετικές σημασίες σε διαφορετικά πλαίσια), χρησιμοποίησε το "x < ? < y (μεγαλύτερο από x και μικρότερο από y)".
  • Αντί να χρησιμοποιείς "esoteric terms", χρησιμοποίησε τη φράση "terms not understood by the majority of people".

Κώδικας

Όλος ο κώδικας πρέπει να μορφοποιείται με συνέπεια, ακολουθώντας τις συμβάσεις στυλ του track τους. Όταν είναι δυνατόν, αυτές οι συμβάσεις σε επίπεδο track θα πρέπει να συμφωνούν με τις προτιμώμενες συμβάσεις στυλ της γλώσσας.