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

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

Το Πρότυπο Κωδικοποίησης Nette αντιστοιχεί στο Εκτεταμένο Στυλ Κωδικοποίησης PSR-12 με δύο κύριες εξαιρέσεις: χρησιμοποιεί tabs αντί για κενά για εσοχές και χρησιμοποιεί PascalCase για τις σταθερές κλάσεων.

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

• Κάθε αρχείο PHP πρέπει να περιέχει declare(strict_types=1)
• Δύο κενές γραμμές χρησιμοποιούνται για το διαχωρισμό των μεθόδων για καλύτερη αναγνωσιμότητα.
• Ο λόγος χρήσης του τελεστή shut-up πρέπει να τεκμηριώνεται: @mkdir($dir); // @ - directory may exist
• Εάν χρησιμοποιείται ασθενής τυποποιημένος τελεστής σύγκρισης (π.χ. ==, !=, …), η πρόθεση πρέπει να τεκμηριώνεται: // == to accept null
• Μπορείτε να γράψετε περισσότερες εξαιρέσεις σε ένα αρχείο exceptions.php
• Η ορατότητα των μεθόδων δεν καθορίζεται για τις διασυνδέσεις επειδή είναι πάντα δημόσιες.
• Κάθε ιδιότητα, τιμή επιστροφής και παράμετρος πρέπει να έχει καθορισμένο τύπο. Από την άλλη πλευρά, για τις τελικές σταθερές, δεν καθορίζουμε ποτέ τον τύπο επειδή είναι προφανής.
• Τα απλά εισαγωγικά πρέπει να χρησιμοποιούνται για να οριοθετούν τη συμβολοσειρά, εκτός αν το ίδιο το λεκτικό περιέχει αποσιωπητικά.

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

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

Περιτύλιξη και αγκύλες

Το πρότυπο κωδικοποίησης Nette αντιστοιχεί στο PSR-12 (ή PER Coding Style), σε ορισμένα σημεία το διευκρινίζει περισσότερο ή το τροποποιεί:

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

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

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

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

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

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

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

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

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

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

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

• Αρχίζει με μια σύντομη περιγραφή της μεθόδου.
• Δεν υπάρχει κενή γραμμή.
• Οι σημειώσεις @param, μία ανά γραμμή.
• Ο σχολιασμός @return.
• Οι σχολιασμοί @throws, ένας προς μία γραμμή.
• Μπορούν να χρησιμοποιηθούν οι σχολιασμοί @internal ή @deprecated.

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

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

Καρτέλες αντί για κενά

Οι καρτέλες έχουν πολλά πλεονεκτήματα έναντι των διαστημάτων:

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

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

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