Πρότυπο κωδικοποίησης

Αυτό το έγγραφο περιγράφει τους κανόνες και τις συστάσεις για την ανάπτυξη του Nette. Κατά τη συνεισφορά κώδικα στο Nette, πρέπει να τους τηρείτε. Ο ευκολότερος τρόπος για να το κάνετε αυτό είναι να μιμηθείτε τον υπάρχοντα κώδικα. Στόχος είναι όλος ο κώδικας να φαίνεται σαν να τον έγραψε ένα άτομο.

Το Nette Coding Standard αντιστοιχεί στο PSR-12 Extended Coding Style με δύο κύριες εξαιρέσεις: για την εσοχή χρησιμοποιεί tabs αντί για κενά και για τις σταθερές κλάσεων χρησιμοποιεί PascalCase.

Γενικοί κανόνες

• Κάθε αρχείο PHP πρέπει να περιέχει declare(strict_types=1)
• Δύο κενές γραμμές χρησιμοποιούνται για τον διαχωρισμό μεθόδων για καλύτερη αναγνωσιμότητα.
• Ο λόγος χρήσης του τελεστή shut-up πρέπει να τεκμηριώνεται: @mkdir($dir); // @ - ο κατάλογος μπορεί να υπάρχει.
• Αν χρησιμοποιείται τελεστής σύγκρισης με αδύναμη τυποποίηση (δηλ. ==, !=, …), πρέπει να τεκμηριώνεται η πρόθεση: // == αποδοχή null
• Σε ένα αρχείο exceptions.php μπορείτε να γράψετε πολλαπλές εξαιρέσεις.
• Στα interfaces δεν καθορίζεται η ορατότητα των μεθόδων, επειδή είναι πάντα public.
• Κάθε property, τιμή επιστροφής και παράμετρος πρέπει να έχει δηλωμένο τύπο. Αντίθετα, στις τελικές σταθερές δεν δηλώνουμε ποτέ τον τύπο, επειδή είναι προφανής.
• Για τον περιορισμό ενός string θα πρέπει να χρησιμοποιούνται απλά εισαγωγικά, εκτός από τις περιπτώσεις όπου το ίδιο το literal περιέχει αποστρόφους.

Συμβάσεις ονοματοδοσίας

• Μην χρησιμοποιείτε συντομογραφίες, εκτός αν το πλήρες όνομα είναι πολύ μεγάλο.
• Για διγράμματες συντομογραφίες χρησιμοποιήστε κεφαλαία γράμματα, για μεγαλύτερες συντομογραφίες pascal/camel.
• Για το όνομα της κλάσης χρησιμοποιήστε ουσιαστικό ή φράση.
• Τα ονόματα των κλάσεων πρέπει να περιέχουν όχι μόνο την εξειδίκευση (Array), αλλά και τη γενικότητα (ArrayIterator). Εξαίρεση αποτελούν τα attributes της γλώσσας PHP.
• Οι σταθερές κλάσεων και τα enums πρέπει να χρησιμοποιούν PascalCaps.
• Τα Interfaces και οι abstract κλάσεις δεν πρέπει να περιέχουν προθέματα ή επιθήματα όπως Abstract, Interface ή I.

Wrapping and Braces

Το Nette Coding Standard αντιστοιχεί στο PSR-12 (ή PER Coding Style), σε ορισμένα σημεία το συμπληρώνει ή το τροποποιεί:

• οι arrow functions γράφονται χωρίς κενό πριν την παρένθεση, δηλ. fn($a) => $b
• δεν απαιτείται κενή γραμμή μεταξύ διαφορετικών τύπων use import statements
• ο τύπος επιστροφής της συνάρτησης/μεθόδου και το αρχικό άγκιστρο είναι πάντα σε ξεχωριστές γραμμές:

	public function find(
		string $dir,
		array $options,
	): array
	{
		// σώμα μεθόδου
	}

Το αρχικό άγκιστρο σε ξεχωριστή γραμμή είναι σημαντικό για τον οπτικό διαχωρισμό της υπογραφής της συνάρτησης/μεθόδου από το σώμα. Αν η υπογραφή είναι σε μία γραμμή, ο διαχωρισμός είναι σαφής (εικόνα αριστερά), αν είναι σε πολλές γραμμές, στο PSR οι υπογραφές και το σώμα συγχωνεύονται (μέση), ενώ στο πρότυπο Nette παραμένουν διαχωρισμένα (δεξιά):

Μπλοκ τεκμηρίωσης (phpDoc)

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

Μπλοκ τεκμηρίωσης για ορισμό κλάσης:

• Ξεκινά με την περιγραφή της κλάσης.
• Ακολουθεί μια κενή γραμμή.
• Ακολουθούν οι annotations @property (ή @property-read, @property-write), μία μετά την άλλη. Η σύνταξη είναι: annotation, κενό, τύπος, κενό, $όνομα.
• Ακολουθούν οι annotations @method, μία μετά την άλλη. Η σύνταξη είναι: annotation, κενό, τύπος επιστροφής, κενό, όνομα(τύπος $param, …).
• Η annotation @author παραλείπεται. Η συγγραφή διατηρείται στην ιστορία του πηγαίου κώδικα.
• Μπορούν να χρησιμοποιηθούν οι annotations @internal ή @deprecated.

/**
 * MIME message part.
 *
 * @property string $encoding
 * @property-read array $headers
 * @method string getSomething(string $name)
 * @method static bool isEnabled()
 */

Το μπλοκ τεκμηρίωσης για μια ιδιότητα, που περιέχει μόνο την annotation @var, θα πρέπει να είναι μονογραμμικό:

/** @var string[] */
private array $name;

Μπλοκ τεκμηρίωσης για ορισμό μεθόδου:

• Ξεκινά με μια σύντομη περιγραφή της μεθόδου.
• Καμία κενή γραμμή.
• Annotations @param σε μεμονωμένες γραμμές.
• Annotation @return.
• Annotations @throws, μία μετά την άλλη.
• Μπορούν να χρησιμοποιηθούν οι annotations @internal ή @deprecated.

Μετά από κάθε annotation ακολουθεί ένα κενό, εκτός από το @param, μετά το οποίο για καλύτερη αναγνωσιμότητα ακολουθούν δύο κενά.

/**
 * Finds a file in directory.
 * @param  string[]  $options
 * @return string[]
 * @throws DirectoryNotFoundException
 */
public function find(string $dir, array $options): array

Tabs αντί για κενά

Τα tabs έχουν αρκετά πλεονεκτήματα έναντι των κενών:

• το μέγεθος της απόστασης μπορεί να προσαρμοστεί στους επεξεργαστές και στο web
• δεν επιβάλλουν στον κώδικα την προτίμηση του χρήστη για το μέγεθος της εσοχής, οπότε ο κώδικας είναι πιο φορητός
• μπορούν να γραφτούν με ένα πάτημα πλήκτρου (οπουδήποτε, όχι μόνο σε επεξεργαστές που μετατρέπουν τα tabs σε κενά)
• η εσοχή είναι ο σκοπός τους
• σέβονται τις ανάγκες των συναδέλφων με προβλήματα όρασης και των τυφλών

Χρησιμοποιώντας tabs στα project μας, επιτρέπουμε την προσαρμογή του πλάτους, η οποία μπορεί να φαίνεται περιττή στους περισσότερους ανθρώπους, αλλά είναι απαραίτητη για άτομα με προβλήματα όρασης.

Για τους τυφλούς προγραμματιστές που χρησιμοποιούν οθόνες Braille, κάθε κενό αντιπροσωπεύει ένα κελί Braille. Αν λοιπόν η προεπιλεγμένη εσοχή είναι 4 κενά, η εσοχή 3ου επιπέδου σπαταλά 12 πολύτιμα κελιά Braille πριν καν αρχίσει ο κώδικας. Σε μια οθόνη 40 κελιών, η οποία χρησιμοποιείται συχνότερα σε φορητούς υπολογιστές, αυτό είναι περισσότερο από το ένα τέταρτο των διαθέσιμων κελιών που σπαταλούνται χωρίς καμία πληροφορία.