Βάζοντας σχόλια σε κώδικα: το καλό, το κακό και το άσχημο.

Σταμάτα με αν το είχες ακούσει πριν…

"Ο καλός κώδικας είναι αυτο-τεκμηρίωση."

Σε 20+ χρόνια σύνταξης κώδικα για τα προς το ζην, αυτή είναι η μόνη φράση που έχω ακούσει περισσότερο.

Είναι κλισέ.

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

Είναι αλήθεια? Ναι .

Σημαίνει ότι δεν πρέπει ποτέ να σχολιάσετε τον κωδικό σας; Όχι .

Σε αυτό το άρθρο θα εξετάσουμε το καλό, το κακό και το άσχημο όταν πρόκειται να σχολιάσουμε τον κώδικά σας.

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

Σχόλια τεκμηρίωσης

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

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

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

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

Εάν γράφετε σχόλια τεκμηρίωσης, θα πρέπει να βεβαιωθείτε ότι ακολουθούν ένα σταθερό πρότυπο και ότι διακρίνονται εύκολα από τυχόν ενσωματωμένα σχόλια διευκρίνισης που μπορεί επίσης να θέλετε να προσθέσετε. Μερικά δημοφιλή και καλά υποστηριζόμενα πρότυπα και εργαλεία περιλαμβάνουν JSDoc για JavaScript, DocFx για dotNet και JavaDoc για Java.

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

Σχόλια διευκρίνισης

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

Συχνά, ένα σχόλιο διευκρίνισης είναι μια μυρωδιά κώδικα. Σας λέει ότι ο κώδικάς σας είναι πολύ περίπλοκος. Θα πρέπει να προσπαθήσετε να καταργήσετε τα σχόλια διευκρίνισης και να απλοποιήσετε τον κώδικα αντ 'αυτού επειδή, "ο καλός κώδικας είναι αυτο-τεκμηρίωση".

Ακολουθεί ένα παράδειγμα κακού - αν και πολύ διασκεδαστικού - σχολιασμού.

/* * Replaces with spaces * the braces in cases * where braces in places * cause stasis.**/ $str = str_replace(array("\{","\}")," ",$str);

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

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

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

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

Όπως, μην κάνετε αυτή την ανοησία:

/*set the value of the age integer to 32*/int age = 32;

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

Συνήθως αυτό συμβαίνει όταν πρέπει να προσθέσετε κάποιο πλαίσιο σε μια μη διαισθητική λύση.

Εδώ είναι ένα καλό παράδειγμα από τον Lodash:

function addSetEntry(set, value) { /* Don't return `set.add` because it's not chainable in IE 11. */ set.add(value); return set; }

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

Μερικές φορές αυτός ο άλλος κωδικοποιητής είναι ο μελλοντικός σας εαυτός.

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

Το ακόλουθο mock-comment αποτυπώνει τέλεια αυτό το σενάριο:

/**Dear maintainer: Once you are done trying to 'optimize' this routine,and have realized what a terrible mistake that was,please increment the following counter as a warningto the next guy: total_hours_wasted_here = 42**/

Again, the above is more about being funny than being helpful. But you SHOULD leave a comment warning others not to pursue some seemingly obvious “better solution,” if you’ve already tried and rejected it. And when you do, the comment should specify what solution you tried and why you decided against it.

Here’s a simple example in JavaScript:

/* don't use the global isFinite() because it returns true for null values*/Number.isFinite(value)

The Ugly

So, we’ve looked at the good and the bad, but what about the ugly?

Unfortunately, there are times in any job where you’ll find yourself frustrated and when you write code for a living, it can be tempting to vent that frustration in code comments.

Work with enough code bases and you’ll come across comments that range from cynical and depressing to dark and mean spirited.

Things like the seemingly harmless…

/*This code sucks, you know it and I know it. Move on and call me an idiot later.*/

…to the downright mean

/* Class used to workaround Richard being a f***ing idiot*/

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

Μην το κάνεις αυτό.

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