Σχόλια στον κώδικα: απαραίτητα ή χάσιμο χρόνου;
Σκεφτείτε το έτσι: Φανταστείτε να σας δίνουν όλα τα υλικά για να φτιάξετε ψωμί, αλλά χωρίς συνταγή. Ξέρετε ότι τα ξηρά υλικά αναμειγνύονται, αλλά ίσως δεν γνωρίζετε τις ποσότητες του καθενός. Το ίδιο ισχύει και με τα σχόλια κώδικα που μπορούν να χρησιμεύσουν ως μια σύντομη περίληψη του τρόπου με τον οποίο ένας προγραμματιστής χρησιμοποίησε μια συνάρτηση ή πώς κάτι άλλαξε για να αντιμετωπιστεί μια συγκεκριμένη πρόκληση.
Τα σχόλια κώδικα είναι απαραίτητα για αποτελεσματικό και αποδοτικό προγραμματισμό. Ο Joel Spolsky (συνιδρυτής του StackOverflow) είπε κάποτε: "Είναι πιο δύσκολο να διαβάζεις κώδικα παρά να τον γράφεις". Γιατί αυτό ισχύει τόσο πολύ; Ένας από τους λόγους είναι τα κακά σχόλια. Όταν οι προγραμματιστές δεν σχολιάζουν τον κώδικα τους, γίνεται σχεδόν αδύνατο να αποκρυπτογραφηθεί τι συμβαίνει. Αλλά με έναν καλό χάρτη σχολίων, αυτός ο "μιζερός" κώδικας είναι πολύ πιο εύκολο να κατανοηθεί.
Τα σχόλια κώδικα:
- Βελτιώνουν την αναγνωσιμότητα: Ο κώδικας με σχόλια είναι πιο εύκολος να κατανοηθεί από οποιονδήποτε τον διαβάζει, είτε πρόκειται για τον αρχικό προγραμματιστή, είτε για κάποιον άλλο προγραμματιστή που καλείται να συνεργαστεί πάνω στο project.
- Αυξάνουν τη συντηρησιμότητα: Τα σχόλια βοηθούν στην εύρεση και διόρθωση σφαλμάτων, καθώς και στην τροποποίηση και επέκταση του κώδικα στο μέλλον.
- Ενισχύουν τη συνεργασία: Τα σχόλια διευκολύνουν την επικοινωνία μεταξύ των προγραμματιστών, εξηγώντας τις σκέψεις και τις προθέσεις πίσω από τον κώδικα.
- Τεκμηριώνουν τον κώδικα: Τα σχόλια χρησιμεύουν ως τεκμηρίωση, εξηγώντας πώς λειτουργεί ο κώδικας και ποιες είναι οι βέλτιστες πρακτικές για τη χρήση του.
Καλλιέργεια καλών συνηθειών σχολιασμού:
- Ενθαρρύνετε τους προγραμματιστές σας να σχολιάζουν τον κώδικα τους όσο τον γράφουν.
- Παρέχετε οδηγίες και κατευθύνσεις για το τι και πώς να σχολιάζουν.
- Δώστε έμφαση στη σαφήνεια, τη συντομία και την ακρίβεια στα σχόλια.
- Ελέγξτε τακτικά τον κώδικα για να βεβαιωθείτε ότι τα σχόλια είναι ενημερωμένα και χρήσιμα.
Επενδύοντας χρόνο στην καλλιέργεια καλών συνηθειών σχολιασμού, οι προγραμματιστές σας μπορούν να δημιουργήσουν κώδικα που είναι:
- Πιο εύχρηστος
- Πιο εύκολος στη συντήρηση
- Πιο κατανοητός
- Πιο αποτελεσματικός
Αυτό, με τη σειρά του, θα οδηγήσει σε:
- Αυξημένη παραγωγικότητα
- Βελτιωμένη συνεργασία
- Κώδικα υψηλής ποιότητας
Συνεπώς, η καλλιέργεια καλών συνηθειών σχολιασμού αποτελεί ζωτικό κομμάτι της ανάπτυξης λογισμικού.
Για όσους θέλουν να βοηθήσουν τους προγραμματιστές τους να βελτιώσουν τη δουλειά τους, ποια είναι τα πρέπει και τα δεν πρέπει στα σχόλια κώδικα; Ας ρίξουμε μια ματιά.
Τα πρέπει στα σχόλια κώδικα
Χρησιμοποιήστε τα σχόλια για να επικοινωνήσετε: Ένα από τα καλύτερα πράγματα που μπορείτε να βοηθήσετε τους προγραμματιστές σας να καταλάβουν είναι ότι πρέπει να χρησιμοποιούν τα σχόλια ως μέσο για να επικοινωνήσουν τις προθέσεις και τις ενέργειές τους σε άλλους προγραμματιστές. Αν ένας προγραμματιστής συμπεριλάβει καλογραμμένα σχόλια στον κώδικα του, επικοινωνεί με όλους τους συνεργάτες του σχετικά με τα τεκεινόμενα της δουλειάς του.Γράψτε σχόλια με το άλλο άτομο στο μυαλό σας: Στην ίδια γραμμή, οι προγραμματιστές σας πρέπει να θεωρούν ότι τα σχόλια πρέπει να γράφονται έχοντας υπόψη άλλους ανθρώπους. Αυτό το εργαλείο δεν αφορά μόνο το να αφήνουν σημειώσεις για τη δουλειά τους στον εαυτό τους, αλλά και το να βοηθούν τους άλλους να αποκρυπτογραφήσουν τι έχουν κάνει.
Ένας από τους κύριους σκοπούς των σχολίων είναι να βοηθούν τους άλλους προγραμματιστές να καταλάβουν τι συμβαίνει στον κώδικα. Αυτό σημαίνει ότι οι προγραμματιστές σας πρέπει να γράφουν έτσι ώστε οποιοσδήποτε άλλος προγραμματιστής να μπορεί να ανοίξει τη δουλειά τους και να καταλάβει τι συμβαίνει.
Αποφύγετε τη σύγχυση: Τα σχόλια κώδικα πρέπει να εξυπηρετούν τον σκοπό της αποφυγής σύγχυσης στον κώδικα. Δεν πρόκειται να επιδείξουν τη δουλειά τους, αλλά να απλοποιήσουν τη διαδικασία συνεργασίας και κατανόησης. Η σαφήνεια και η προφανότητα της δουλειάς τους πρέπει να είναι ο πρωταρχικός στόχος των σχολίων κώδικα.
Αυτό σημαίνει επίσης ότι τα σχόλια του προγραμματιστή σας θα πρέπει επίσης να είναι πολύ σαφή και περιεκτικά (και να μην προσθέτουν ακόμη περισσότερη σύγχυση).
Παρέχετε συνδέσμους στην αρχική πηγή του αντιγραμμένου κώδικα: Εάν οι προγραμματιστές σας αντιγράψουν κώδικα από άλλες πηγές (πχ StackOverflow), θα πρέπει πάντα να αφήνουν συνδέσμους στις αρχικές πηγές. Γιατί; Επειδή όποιος ακολουθήσει τα βήματά τους μπορεί να χρειαστεί να κατανοήσει γιατί χρησιμοποίησαν αυτό το κομμάτι κώδικα και ποια ήταν η αρχική του πρόθεση, και ίσως χρειαστεί ακόμη και να επικοινωνήσει με τον προγραμματιστή του αντιγραμμένου κώδικα.
Προσθέστε σχόλια κατά την διόρθωση σφαλμάτων: Τα σχόλια κώδικα δεν προορίζονται μόνο για τον αρχικό (ή αντιγραμμένο) κώδικα, αλλά και για όταν οι προγραμματιστές σας διορθώνουν σφάλματα. Αυτά τα σχόλια θα πρέπει να εξηγούν τι έκαναν για να διορθώσουν το σφάλμα και γιατί ήταν απαραίτητο. Ωστόσο, οι προγραμματιστές σας δεν θα πρέπει να γράφουν μακροσκελείς οδηγίες στα σχόλια, αλλά θα πρέπει να είναι περιεκτικοί και αποτελεσματικοί στη διατύπωσή τους.
Χρησιμοποιήστε σχολιασμούς ή ετικέτες κώδικα: Για να κάνουν τα πράγματα πιο περιεκτικά, οι προγραμματιστές σας θα πρέπει να χρησιμοποιούν σχολιασμούς και ετικέτες κώδικα. Για παράδειγμα, το @desc θα είναι μια περιγραφή, το @param θα είναι μια περιγραφή των παραμέτρων, το @returns περιγράφει την επιστρεφόμενη έξοδο και το @throws περιγράφει πιθανούς τύπους σφαλμάτων. Οι περισσότεροι προγραμματιστές θα πρέπει να έχουν μια καλή κατανόηση αυτών των σχολιασμών και ετικετών. Εάν όχι, βεβαιωθείτε ότι θα μάθουν γι' αυτές.
Γράψτε σχόλια ενώ γράφετε τον κώδικα: Αντί να επιστρέφουν οι προγραμματιστές σας αφού ολοκληρωθεί ο κώδικας για να εισάγουν σχόλια, θα πρέπει να τα γράφουν κατά τη διάρκεια της συγγραφής. Αυτό μπορεί να αποτρέψει πολλά προβλήματα. Πρώτον, θα αποφύγει το ενδεχόμενο ένας προγραμματιστής να ξεχάσει γιατί έκανε κάτι. Δεύτερον, εάν συμβεί κάτι σε έναν προγραμματιστή στη μέση του project, τα σχόλια υπάρχουν ήδη, ώστε κάποιος άλλος να μπορεί να συνεχίσει από το σημείο που σταμάτησαν χωρίς ιδιαίτερη δυσκολία.
Τα ΔΕΝ πρέπει στα σχόλια κώδικα
Μη σχολιάζετε τα πάντα: Είναι επίσης σημαντικό οι προγραμματιστές σας να κατανοήσουν ότι δεν πρέπει να σχολιάζουν κάθε μικρό πράγμα. Οι προγραμματιστές δεν πρέπει να σχολιάζουν το προφανές. Αυτό το λάθος συμβαίνει συχνά με νέους προγραμματιστές που νιώθουν ότι πρέπει να τεκμηριώσουν τα πάντα που δημιουργούν κατά τη διαδρομή.Για να βοηθήσετε σε αυτό, ζητήστε από τους προγραμματιστές σας να σκεφτούν εάν αυτό που γράφουν ακολουθεί ευρέως αποδεκτές συμβάσεις και συντακτικές δομές, που σημαίνει ότι πιθανότατα δεν χρειάζεται σχόλιο.
Μη χρησιμοποιείτε τα σχόλια ως υποκατάστατο της τεκμηρίωσης: Τα σχόλια κώδικα και η τεκμηρίωση δεν είναι το ίδιο πράγμα. Δεν θέλετε οι προγραμματιστές να χρησιμοποιούν τα σχόλια ως τεκμηρίωση επειδή ο κώδικας μπορεί να καταλήξει να είναι πολύ μεγάλος (και συγκεχυμένος) και να προκαλεί περιττή εργασία. Αυτό συμβαίνει συχνά επειδή οι προγραμματιστές απεχθάνονται να γράφουν τεκμηρίωση (διαβάστε το άρθρο).
Τα σχόλια κώδικα υπάρχουν για να εξηγήσουν συγκεκριμένες λειτουργίες και προσεγγίσεις, όχι για να περιγράψουν πώς λειτουργεί κάτι λεπτομερώς. Εάν οι προγραμματιστές σας προσθέτουν περιττές πληροφορίες στα σχόλια κώδικα τους, πρέπει να σταματήσετε αυτή τη συμπεριφορά πριν ξεφύγει από τον έλεγχο.
Μη αναφέρεστε σε άλλα σχόλια στα σχόλιά σας: Εάν οι προγραμματιστές σας αναφέρονται σε άλλα σχόλια (ή ακόμα και σε άλλα έγγραφα), δίνουν σε άλλους προγραμματιστές περισσότερη δουλειά από όσο χρειάζεται. Σκεφτείτε το εξής: Ένας προγραμματιστής τοποθετεί ένα σχόλιο μέσα στον κώδικα που αναφέρεται σε άλλο σχόλιο. Αυτό σημαίνει ότι ένας προγραμματιστής που ακολουθεί αυτό το άτομο θα πρέπει στη συνέχεια να αναζητήσει στον κώδικα για να βρει το σχόλιο που αναφέρεται. Αυτό είναι υπερβολική δουλειά.
Αντί να αναφέρεται σε άλλο σχόλιο, ο προγραμματιστής σας θα πρέπει να ξεκαθαρίσει τι θέλει να πει (και να το κάνει αποτελεσματικά). Ο στόχος πρέπει να είναι να δώσει λιγότερη δουλειά στους άλλους, όχι περισσότερη.
Συμπέρασμα
Τα σχόλια κώδικα είναι εξίσου σημαντικά με τον πραγματικό κώδικα, επειδή βοηθούν να κάνουν τη δουλειά όλων ευκολότερη. Αν μπορείτε να καλλιεργήσετε καλές συνήθειες σχολιασμού στους προγραμματιστές σας από την αρχή, μπορείτε να είστε σίγουροι ότι ο καθένας μπορεί να πάρει στα χέρια τον κώδικα ενός άλλου προγραμματιστή και να ξέρει ακριβώς τι έγινε, γιατί έγινε και πώς έγινε.Σε όσους προγραμματιστές (ή γουαναμπι προγραμματιστές) έχω ρωτήσει αν γράφουν σχόλια στον κώδικά τους, η απάντηση είναι:
Εγώ γράφω κώδικα που είναι ευανάγνωστος. Δεν χρειάζεται σχόλια.
Καλά θα πάει αυτό!!!
Leave a Comment