Βέλτιστες πρακτικές αναθεώρησης κώδικα

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

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

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

Ο πελάτης επωφελείται από τις αλλαγές και τις λύσεις που αναπτύσσονται γρήγορα και με αυτοπεποίθηση. Μαζί με άλλες βέλτιστες πρακτικές (όπως μεγάλη κάλυψη δοκιμών, CI/CD, περιβάλλοντα σταδιοποίησης κ.λπ.), οι αναθεωρήσεις κώδικα διασφαλίζουν επίσης ότι αυτό που αναπτύσσεται είναι ασφαλές, υγιές και πληροί τις απαιτήσεις όπως έχουν καθοριστεί.

Σκοπός και χρήση αυτών των κατευθυντήριων γραμμών

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

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

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

Αρμοδιότητες σχετικά με την αναθεώρηση κώδικα

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

Επικεφαλής του έργου

• DO να διασφαλίσετε ότι τα αποθετήριά σας είναι καλά ρυθμισμένα (π.χ. οι συγχωνεύσεις στον κλάδο σας που αφορά την παραγωγή δεν επιτρέπονται χωρίς τουλάχιστον μία εγκριτική αναθεώρηση).
• DO να διασφαλίσετε ότι η ομάδα σας κατανοεί και εφαρμόζει αυτές τις πρακτικές και να εργαστείτε ενεργά για να προωθήσετε την κατανόηση του γιατί κάνουμε τα πράγματα με έναν συγκεκριμένο τρόπο.
• DO να προσέχετε τυχόν καταστάσεις ισοπαλίας, όπου οι αντίθετες απόψεις δεν μπορούν να επιλυθούν: ως τεχνικός ηγέτης της ομάδας σας, είναι δική σας ευθύνη να επιλέξετε την πιο κατάλληλη λύση σε τέτοιες περιπτώσεις και να συνεχίσετε την πρόοδο των εργασιών.
• Ωστόσο, ΜΗΝ χρησιμοποιούν την ηγεσία του έργου ως αμβλύ εργαλείο. ΜΗΝ "pull rank". DO καλωσορίζετε την αναθεώρηση και την κριτική των λύσεών σας, όσο και αν τις ενθαρρύνετε για το έργο οποιουδήποτε.
• ΣΚΕΦΤΕΙΤΕ να προσθέσετε μια ενσωμάτωση του GitHub στο κανάλι Slack της ομάδας σας. Μπορεί να είναι χρήσιμο για την καλύτερη τοποθέτηση των αιτημάτων αναθεώρησης στα ραντάρ των αναθεωρητών, αλλά ανάλογα με τον συνολικό όγκο του καναλιού σας, αυτό μπορεί να είναι ή να μην είναι κατάλληλο για την ομάδα σας.

Μέλος της ομάδας

• ΣΥΜΜΕΤΕΧΕΤΕ σε ανασκοπήσεις κώδικα. Δεν είναι αποδεκτό να μην αναθεωρείτε τον κώδικα.
• Θυμηθείτε να κάνετε τις ανασκοπήσεις κώδικα: οι συνάδελφοί σας εξαρτώνται από εσάς για να προχωρήσει η δουλειά τους!
• Εάν δεν μπορείτε να κάνετε μια συγκεκριμένη αναθεώρηση, DO επικοινωνήστε το με σαφήνεια και ανοιχτά.
• Ωστόσο, ΜΗΝ να υποθέσετε ότι δεν μπορείτε να κάνετε μια συγκεκριμένη αναθεώρηση επειδή δεν γνωρίζετε τη συγκεκριμένη ενότητα/πλευρά του συστήματος/τις προδιαγραφές της επιχειρηματικής λογικής. Η ανασκόπηση κώδικα είναι μια σημαντική ευκαιρία μάθησης.
• Αν νιώθετε ότι δεν ξέρετε αρκετά για κάτι ώστε να κάνετε μια κριτική, DO ρωτήστε τον συγγραφέα σχετικά: θα χαρεί να σας εξηγήσει τι υποτίθεται ότι κάνουν οι αλλαγές.
• ΜΗΝ να απορρίπτετε κριτικές με βάση το επίπεδο εμπειρίας (το δικό σας ή του συγγραφέα).
• DO προσπαθήστε να αναθεωρείτε τουλάχιστον όσες δημόσιες σχέσεις παράγετε. Ιδανικά, διατηρήστε την αναλογία της αναθεώρησης που δίνεται προς την απαιτούμενη αναθεώρηση πάνω από 1 (ειδικά σε μεγαλύτερες ομάδες).

Συγγραφέας

• DO να καταλάβετε ότι είναι δική σας ευθύνη να αναθεωρείτε τον κώδικά σας - η ομάδα σας μπορεί να αναζητά προληπτικά αιτήσεις για αναθεώρηση, αλλά δεν είναι υποχρεωμένη να το κάνει.
• ΜΗΝ να αναθέτετε/ζητάτε κριτικές πάντα από τα ίδια μέλη της ομάδας - θα επωφεληθείτε περισσότερο από μια ποικίλη ομάδα κριτών (και αντίστροφα, ένα ευρύτερο φάσμα προγραμματιστών θα επωφεληθεί από την αναθεώρηση του κώδικά σας)
• ΜΗΝ να αποκλείσετε κάποιον από την αξιολόγηση με βάση την εμπειρία του. Οι νεότεροι προγραμματιστές επωφελούνται από την αναθεώρηση κώδικα. Οι ανώτεροι προγραμματιστές επωφελούνται από την αναθεώρηση κώδικα. Όπως αναφέρεται στον πρόλογο αυτού του εγγράφου, όλοι ωφελείται από την αναθεώρηση του κώδικα.
• ΕΞΕΤΆΣΤΕ ΤΟ χρησιμοποιώντας έναν τυχαιοποιητή για την επιλογή των κριτών σας. Π.χ. στη Ruby, %w[συμπαίκτης1 συμπαίκτης2 συμπαίκτης3].sample μπορεί να κάνει θαύματα.
• DO να αναθέτετε τουλάχιστον δύο κριτές στις αιτήσεις σας, εκτός αν είναι απολύτως αδύνατο. Με αυτόν τον τρόπο περισσότεροι άνθρωποι επωφελούνται από τη διαδικασία (και με τρία άτομα είναι πιο δύσκολο να καταλήξετε σε ισοπαλία).
• DO να ανταποκρίνεστε στις αιτήσεις σας. Παρόλο που δεν πρέπει να διακόψετε τη ροή σας για να απαντήσετε αμέσως σε οποιοδήποτε σχόλιο, βεβαιωθείτε ότι οι απαντήσεις σας είναι έγκαιρες - διαφορετικά οι δημόσιες σχέσεις σας θα παραμένουν στην αναθεώρηση κώδικα επ' αόριστον.
• DO φέρτε μια ανοιχτή στάση. Να υποθέτετε πάντα ότι ο κριτής σας προσπαθεί να βοηθήσει με τις καλύτερες προθέσεις. Εξηγήστε τη λογική σας, αντιμετωπίστε τα επιχειρήματα του κριτή σας και απαντήστε στις ερωτήσεις του.
• DO να είστε ευγενικοί. Οι παρεξηγήσεις συμβαίνουν, αλλά δεν χρειάζεται να ξεφεύγουν από τον έλεγχο και να πλήττουν την ατμόσφαιρα στην ομάδα.
• DO να είσαι ειλικρινής. Αν πιστεύετε ότι αυτή είναι η καλύτερη λύση, πείτε το και παρουσιάστε τα επιχειρήματά σας. Εάν πεισθείτε ότι οι προτάσεις του κριτή σας είναι καλύτερες από αυτές που παρουσιάσατε, πείτε τους το. Εάν πιστεύετε ότι μπορεί να παραχθεί μια λύση "το καλύτερο και από τους δύο κόσμους" χρησιμοποιώντας τόσο τις ιδέες σας όσο και τις ιδέες του κριτή σας, προτείνετε τους την. Τελικά, δουλέψτε προς την κατεύθυνση της συναίνεσης στα αιτήματα διανομής σας.
• DO αφήστε την επίλυση των παρατηρήσεών τους στον αναθεωρητή σας - μην τις επιλύετε απλώς επειδή είστε πεπεισμένοι ότι όλα είναι εντάξει τώρα.
• DO να εξηγήσετε ενεργά την εργασία σας, το σκεπτικό σας και άλλες απαιτήσεις στους κριτές σας. Δεν είναι κακό να μην γνωρίζετε - δεν είναι αποδεκτό να αποκρύπτετε τη γνώση.
• ΜΗΝ να υποθέσετε ότι γνωρίζετε τα πάντα - είμαστε όλοι φοβεροί ειδικοί, αλλά είναι σημαντικό να φέρνετε μια ορισμένη δόση ταπεινότητας στη συνεργασία μαζί σας.
• DO να είναι ο πρώτος κριτής του κώδικά σας. Φορέστε το καπέλο του κριτή και σαρώστε τον κώδικα προσεκτικά, όπως θα κάνατε για το άτομο που δεν συμπαθείτε κυρίως. Εντοπίστε και εξαλείψτε τα πιο προφανή πράγματα, όπως κενές γραμμές, τυχόν περισσεύματα ή ελλείπουσες προδιαγραφές. Μην παραλείψετε τίποτα - το πιθανότερο είναι ότι θα επισημανθεί ούτως ή άλλως. Μην σπαταλάτε τον χρόνο των κριτών!
• DO να περιγράψετε διεξοδικά το αίτημά σας. Η περιγραφή είναι καλή όταν ο κριτής δεν θα εκπλαγεί από τίποτα κατά την ανάγνωση του κώδικα. Να θυμάστε ότι δεν μπορεί να διαβάσει το μυαλό σας. Γι' αυτό είναι σημαντικό να περιγράφετε πράγματα που δεν είναι προφανή, βασικές αποφάσεις με τον λόγο ή όλες τις νέες κλάσεις και αρχεία.
• ΕΞΕΤΆΣΤΕ ΤΟ χρησιμοποιώντας το πρότυπο του pull request. Αν χρησιμοποιείτε το Github, προσθέστε το στο αποθετήριο σας στο τμήμα .github/pull_request_template.md. Ενθαρρύνει όλα τα μέλη της ομάδας να περιγράφουν τα pull requests τους. Είναι επίσης πολύ πιο εύκολο να γράψετε όταν έχετε το πεδίο περιγραφής συμπληρωμένο με ένα πρότυπο. Εδώ μπορείτε να βρείτε ένα πρότυπο που χρησιμοποιούμε σε ένα από τα έργα μας https://gist.github.com/weemanjz/a20ccb9f3f492b9bd21ab026a1d46353

Συγγραφέας

• DO να καταλάβετε ότι είναι δική σας ευθύνη να έχετε αναθεώρηση κώδικα - η ομάδα σας μπορεί να αναζητά προληπτικά αιτήσεις για να τις αναθεωρήσει, αλλά δεν είναι υποχρεωμένη να το κάνει.
• ΜΗΝ να αναθέτετε/ζητάτε πάντα κριτικές από τον ίδιο κριτές κώδικα - θα ωφεληθείτε περισσότερο από μια ποικίλη ομάδα κριτών (και αντίστροφα, ένα ευρύτερο φάσμα προγραμματιστών θα ωφεληθεί από την αναθεώρηση του κώδικά σας)
• ΜΗΝ να αποκλείσετε κάποιον από την αξιολόγηση με βάση την εμπειρία του. Οι νεαροί προγραμματιστές επωφελούνται από την εκτέλεση αναθεωρήσεις κώδικα. Οι ανώτεροι προγραμματιστές επωφελούνται από την εκτέλεση αναθεωρήσεις κώδικα. Όπως αναφέρεται στον πρόλογο του παρόντος εγγράφου, όλοι οφέλη από την εκτέλεση αναθεωρήσεις κώδικα.

Κριτής

• DO χρησιμοποιήστε τη γλώσσα της υπόδειξης αντί της απαίτησης. Αντί να λέτε "Θα πρέπει να βελτίωση της ποιότητας του κώδικα κάνοντας Χ αντί για Χ", ας πούμε "Έχετε σκεφτεί να βελτιώσετε ποιότητα κώδικα κάνοντας Χ;"
• DO εξηγήστε τις προτάσεις σας. "Νομίζω ότι το Χ είναι καλύτερο εδώ γιατί βοηθάει στην μεταφορά γνώσεων και βελτίωση της ποιότητας του κώδικα."
• Ακόμη και αν η πρότασή σας προέρχεται από αντικειμενικές πηγές (π.χ. στυλ κώδικα κατευθυντήριες γραμμές), DO ζητάτε από τον συγγραφέα να κάνει κάτι αντί να του λέτε να κάνει κάτι. "Παρακαλώ κρατήστε όλα τα widgets frobnicated σύμφωνα με μας στυλ κώδικα οδηγός - [σύνδεσμος]"
• ΜΗΝ υποθέστε ότι γνωρίζετε τα πάντα. "Καταλαβαίνω ότι αυτό το widget δεν πρέπει ποτέ να φρομπνικάρει, και υπό αυτές τις συνθήκες θα το κάνει - είναι αυτό μια εξαίρεση που χρειάζεται μια αναθεώρηση κώδικα?"
• DO να χρησιμοποιούν γλώσσα χωρίς αποκλεισμούς. "Πιστεύω ότι θα ήμασταν καλύτερα στο μέλλον αν το χτίζαμε έτσι. Τι πιστεύετε γι' αυτό; καλύτερη αναθεώρηση κώδικα πρόταση;" και "Ίσως θα έπρεπε να χρησιμοποιήσουμε το Χ εδώ αντί για ένα αποτελεσματική αναθεώρηση κώδικα?"
• DO να είστε γρήγοροι στο να κάνετε το αναθεωρήσεις κώδικα. Δεν θα πρέπει να διακόψετε τη ροή σας για να τα κάνετε, αλλά προσπαθήστε να κρατήσετε το βρόχο σφιχτό, αν είναι δυνατόν. Σε μερικούς ανθρώπους αρέσει να τις κάνουν είτε στην αρχή είτε στο τέλος της εργάσιμης ημέρας τους, είτε ως "προθέρμανση" είτε ως "χαλάρωση".

Σημειώστε ότι αυτές οι λέξεις-κλειδιά έχουν εισαχθεί με τρόπο που να διατηρεί το πλαίσιο και τη συνοχή του κειμένου ανέπαφο. Εάν τις θέλετε σε συγκεκριμένα σημεία, διευκρινίστε το.