Σχόλιο (προγραμματισμός)

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

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

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

Γενικά 
Τα σχόλια συνήθως μορφοποιούνται σαν ενότητες σχολίων (block comments), γνωστά και σαν σχόλια προλόγου (prologue comments), ροές σχολίων (stream comments), σχόλια γραμμής (line comments) ή εμβόλιμα σχόλια (inline comments).

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

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

Κάποιες γλώσσες προγραμματισμού περιλαμβάνουν τόσο ενότητες σχολίων, όσο και γραμμές σχολίων, με διαφορετικά διαχωριστικά. Για παράδειγμα η C++ χρησιμοποιεί τα διαχωριστικά /* και */ στις ενότητες σχολίων της που μπορούν να καταλαμβάνουν πολλές γραμμές, και το διαχωριστικό // για τα σχόλια γραμμής. Άλλες γλώσσες υποστηρίζουν μόνο ένα είδος σχολίων. Για παράδειγμα τα σχόλια της Ada είναι σχόλια γραμμής: αρχίζουν με -- και συνεχίζουν μέχρι το τέλος της γραμμής.

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

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

"Μην τεκμηριώνετε κακό κώδικα - ξαναγράψτε τον."

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

Τα σχόλια μπορούν επίσης να χρησιμοποιηθούν για να εξηγήσουν γιατί μια ενότητα κώδικα φαίνεται να μη συμμορφώνεται με συμβάσεις ή γνωστές καλές πρακτικές. Αυτό συμβαίνει ιδιαίτερα σε εγχειρήματα που έχουν πολύ λίγο χρόνο ανάπτυξης ή στη διόρθωση σφαλμάτων. Για παράδειγμα:
' Δεύτερη μεταβλητή λόγω σφαλμάτων εξυπηρετητή κατά την επαναλαμβανόμενη χρήση
' δεδομένων φόρμας. Δεν υπάρχει διαθέσιμη τεκμηρίωση, παρακάμπτεται μέσω κώδικα.
vtx = server.mappath("local settings")

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

Για παράδειγμα, ένας προγραμματιστής μπορεί να προσθέσει ένα σχόλιο για να εξηγήσει γιατί μια ταξινόμηση εισαγωγής (insertion sort) επιλέχθηκε αντί για ταξινόμηση quicksort, καθώς η πρώτη είναι θεωρητικά πιο αργή. Αυτό θα μπορούσε να γραφεί ως εξής:
 list = [f (b), f (b), f (c), f (d), f (a), ...];
 // Χρειάζεται μια σταθερή (stable) ταξινόμηση. Επίσης, η ταχύτητα εδώ δεν έχει σημασία.
 insertion_sort (list);

Συμπερίληψη πόρων 
Στον πηγαίο κώδικα μπορούν να τοποθετηθούν λογότυπα, διαγράμματα (απλά και διαγράμματα ροής), σαν δομές τέχνης ASCII (ASCII art) σε σχόλια. Επιπλέον, σε σχόλια μπορούν να βρίσκονται κείμενα σχετικά με την πνευματική ιδιοκτησία του κώδικα. Στα σχόλια μπορούν να κωδικοποιηθούν και δυαδικά δεδομένα με μια διαδικασία γνωστή σαν "κωδικοποίηση δυαδικό-σε-κείμενο" ("binary-to-text encoding"), αν και κάτι τέτοιο δε συνηθίζεται γιατί προτιμώνται τα εξωτερικά αρχεία.

Αποσφαλμάτωση 
Μια συνηθισμένη τακτική των προγραμματιστών είναι να απενεργοποιούν τμήματα κώδικα με τη χρήση σχολίων (αγγλικα: comment out), για να μην εκτελεστούν στο τελικό πρόγραμμα. Για παράδειγμα, κάποιος μπορεί να γράψει:
 if (opt.equals ("e"))
   opt_enabled = true;
 /*
  if (opt.equals ("d"))
   opt_debug = true;
 // */
 //*
 if (opt.equals ("v"))
    opt_verbose = true;
 // */
Στον παραπάνω κώδικα φαίνεται ότι ο προγραμματιστής επέλεξε να απενεργοποιήσει την επιλογή της αποσφαλμάτωσης για κάποιο λόγο. Το συγκεκριμένο στυλ σχολιασμού είναι καταλληλότερο για αποσφαλμάτωση. Ένας μονός χαρακτήρας καθέτου μπροστά από το αρχικό διαχωριστικό είναι αυτό που ενεργοποιεί ή απενεργοποιεί τις ενότητες σχολίων.

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

Παραδείγματα γεννητριών τεκμηρίωσης είναι το πρόγραμμα javadoc, που σχεδιάστηκε για χρήση με τη Java, το Ddoc για τη γλώσσα προγραμματισμού D, το PHPDoc για την PHP και το doxygen, που χρησιμοποιείται με τη C++, τη C, τη Java και την IDL.

Η C# και η Visual Basic υλοποιούν ένα παρόμοιο χαρακτηριστικό που ονομάζεται "Σχόλια XML" ("XML Comments"), τα οποία διαβάζονται από το μηχανισμό IntelliSense από το μεταγλωττισμένο αρχείο (assembly) του .NET.

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

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

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

Βαθμός λεπτομέρειας 
Το πόσο λεπτομερές και περιγραφικό μπορεί να είναι ένα σχόλιο διαφέρει ανάλογα με το επιθυμητό κοινό και άλλους παράγοντες.

Για παράδειγμα, το εξής σχόλιο σε Java θα μπορούσε να ταιριάζει σε ένα εισαγωγικό κείμενο στον προγραμματισμό:

        String s = "Wikipedia"; /* Αναθέτει την τιμή "Wikipedia" στη μεταβλητή s. */
    

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

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

Τα παρακάτω κομμάτια κώδικα σε C δείχνουν ένα μικρό παράδειγμα σχετικά με το πόσο μπορεί να διαφέρουν στυλιστικά σχόλια, ενώ παρέχουν την ίδια πληροφορία:
/* 
     Τα σώμα των σχολίων.
     Παραλλαγή πρώτη.
*/

/***************************\
*                           *
* Τα σώμα των σχολίων.      *
* Παραλλαγή δεύτερη.        *
*                           *
\***************************/

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

Μια άποψη είναι η στοίχιση των αριστερών άκρων των σχολίων:

  /* Στυλ για τη C και τη C++.
  * Εμφανίζεται στο βιβλίο ''Enough Rope'',<ref name="Holub001" /> στον κανόνα 29.
  */
 

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

Σχόλια μέχρι το τέλος της γραμμής 
Σύμφωνα με αυτήν την άποψη, αγνοείται όλο το κείμενο από τους χαρακτήρες ASCII // μέχρι το τέλος της γραμμής.
/// Παραλλαγή τρίτη.
/// --------------------
/// Το σώμα των σχολίων.
/// --------------------

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

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

Ετικέτες 
Υπάρχουν κάποιες ετικέτες (tags) που χρησιμοποιούνται στα σχόλια για να βοηθούν την ανάλυση κάποιων συνηθισμένων θεμάτων. Αυτές οι ετικέτες συνήθως μορφοποιούνται με χρώματα στο διορθωτή και μπορεί να γίνει αναζήτησή τους με κλασικά προγραμματιστικά εργαλεία, όπως το εργαλείο grep του UNIX. Παραδείγματα συμβάσεων για ετικέτες:

 FIXME που δείχνει κώδικα που πιθανόν να έχει πρόβλημα και χρειάζεται αναθεώρηση.
 NOTE που τεκμηριώνει εσωτερικές λειτουργίες του κώδικα και δείχνει πιθανά προβλήματα.
 TODO για προγραμματισμένες βελτιώσεις.
 XXX που προειδοποιεί άλλους προγραμματιστές για προβληματικό ή παραπλανητικό κώδικα.

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

Παραδείγματα

C 
Το παρακάτω μέρος κώδικα σε C δείχνει τη χρήση των σχολίων προλόγου ή "ενοτήτων σχολίων" για την περιγραφή μιας εντολής υπό συνθήκη. Το σχόλιο εξηγεί βασική ορολογία και έννοιες και περιλαμβάνει μια μικρή υπογραφή του προγραμματιστή που έγραψε τον κώδικα.
 /*
  * Ελέγχει αν είμαστε πάνω από το μέγιστο όριο διεργασιών, χωρίς όμως
  * να περιλαμβάνει το root. Αυτό χρειάζεται ώστε η login και οι παρόμοιες
  * με αυτήν να μπορούν να ορίζουν το όριο διεργασιών ανά χρήστη σε κάτι μικρότερο
  * από τις διεργασίες που τρέχει ο root. -- Rik
  */
 if (atomic_read(&p->user->processes) >= p->rlim[RLIMIT_NPROC].rlim_cur
     && !capable(CAP_SYS_ADMIN) && !capable(CAP_SYS_RESOURCE))
     goto bad_fork_free;
Το παραπάνω απόσπασμα είναι από το αρχείο fork.c από τον πηγαίο κώδικα του πυρήνα Linux.

Κλασική BASIC 
Αυτό το απόσπασμα κώδικα σε BASIC είναι ένα πλήρες πρόγραμμα στο οποίο τα σχόλια περιγράφουν τη λειτουργία του στους αρχάριους προγραμματιστές.
10 REM Αυτό το πρόγραμμα σε BASIC δείχνει τη χρήση των εντολών PRINT και GOTO.
15 REM Γεμίζει την οθόνη με τη λέξη "WIKIPEDIA".
20 PRINT "WIKIPEDIA"
30 GOTO 20
Όταν εκτελεστεί, το πρόγραμμα τυπώνει συνέχεια (σε ατέρμονα βρόχο) τη λέξη "WIKIPEDIA" (χωρίς τα εισαγωγικά).

ColdFusion 
Το ColdFusion χρησιμοποιεί σχόλια παρόμοια με αυτά της HTML/XML, αλλά αντί για δύο παύλες χρησιμοποιεί τρεις. Τα σχόλια ανιχνεύονται από τη μηχανή του ColdFusion και δεν εμφανίζονται στο φυλλομετρητή.

 <!--- Τυπώνει "Hello World" στο φυλλομετρητή. --->
 <cfoutput>
   Hello World<br />
 </cfoutput>

Fortran 90 
Ο παρακάτω κώδικας σε Fortran δείχνει πώς χρησιμοποιούνται τα σχόλια σε αυτήν τη γλώσσα, με τα ίδια τα σχόλια να περιγράφουν βασικούς κανόνες μορφοποίησης.
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
!* Όλοι οι χαρακτήρες μετά το θαυμαστικό θεωρούνται σχόλια             *
!* * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * *
 
       PRINT "WIKIPEDIA" ! Η Fortran 90 εισήγαγε τα εμβόλιμα σχόλια.
       END

Java 
Το παρακάτω απόσπασμα κώδικα σε Java δείχνει μια ενότητα σχολίων που χρησιμοποιείται για να περιγράψει τη μέθοδο setToolTipText. Η μορφοποίηση συμφωνεί με τα πρότυπα του Javadoc της Sun Microsystems. Το σχόλιο με αυτήν τη μορφή είναι έτοιμο για να αναγνωριστεί από τον επεξεργαστή του javadoc.
 /**
  * Καταχωρεί το κείμενο που θα εμφανίζεται σε ένα "tool tip". Το κείμενο
  * εμφανίζεται όταν ο δείκτης βρίσκεται πάνω σε ένα στοιχείο.
  *
  * @param text  το κείμενο που θα εμφανιστεί. Αν δε δίνεται κείμενο (null), 
  *              το "tool tip" απενεργοποιείται για αυτό το στοιχείο.
  */
 public void setToolTipText(String text) {

Perl 
Τα σχόλια γραμμής στην Perl, και σε άλλες γλώσσες σεναρίων, αρχίζουν με ένα σύμβολο δίεσης (#). Ένα σχόλιο στην αρχή, λέει στο σύστημα ποιόν διερμηνέα να χρησιμοποιήσει.
#!/usr/bin/perl
my $s = "Wikipedia"; # Θέτει τη μεταβλητή s ίση με "Wikipedia".
print $s . "\n";     # Προσθέτει ένα χαρακτήρα νέας γραμμής μετά από την εκτύπωση για κελύφη που δεν το κάνουν αυτόματα.

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

Python 
Τα σχόλια στην Python μπορεί να είναι μίας γραμμής ή πολλαπλών γραμμών χρησιμοποιούν το χαρακτήρα της δίεσης.

Σχολιασμός μιας γραμμής:(αρχίζει με το σύμβολο "#")

#!/usr/bin/env python
# -*- coding: utf-8 -*-
# αυτό το πρόγραμμα τυπώνει "Hello World" στην οθόνη και τερματίζει.
print "Hello World!"#TODO:Να προσθέσω και μία ακόμα γραμμή κάποια στιγμή
Προσοχή! Τα προγράμματα σε Python μπορεί να αρχίζουν με το σύμβολο "#!" που λέει στο λειτουργικό σύστημα ποιoν διερμηνέα να χρησιμοποιήσει και έτσι να μπορούν να οριστούν σαν εκτελέσιμα.

Σχολιασμός πολλαπλών γραμμών: (τα σχόλια βρίσκονται ανάμεσα σε τριπλά εισαγωγικά, μονά ή διπλά)
#!/usr/bin/env python
# -*- coding: utf-8 -*-
''' Αυτό το πρόγραμμα τυπώνει "Hello World" στην οθόνη και τερματίζει.

    Μπορείτε να το χρησιμοποιήσετε κατά βούληση.
'''
print "Hello World!"
Ο σχολιασμός πολλαπλών γραμμών στην Python χρησιμοποιείται από διάφορα προγράμματα για την παραγωγή τεκμηρίωσης.

Ruby 
Τα σχόλια σε Ruby

Σχολιασμός μιας γραμμής: (η γραμμή αρχίζει με το σύμβολο "#")
Αυτό δεν είναι σχόλιο

#αυτό είναι σχόλιο

Αυτό δεν είναι σχόλιο

Σχολιασμός πολλαπλών γραμμών: (τα σχόλια βρίσκονται μεταξύ των λέξεων-κλειδιών "begin" και "end")
Αυτό δεν είναι σχόλιο

=begin

οτιδήποτε τοποθετείται εδώ

αγνοείται :)

=end

Αυτό δεν είναι σχόλιο

SQL 
Τα σχόλια στην SQL είναι μόνο μιας γραμμής, όταν χρησιμοποιούνται δύο παύλες:
-- Ένα σχόλιο μιας γραμμής
-- ακολουθούμενο από άλλη μια γραμμή
SELECT COUNT(*) 
       FROM Authors
       WHERE Authors.name = 'Smith'; -- Σημείωση: θέλουμε μόνο το 'smith'
                                     -- αυτό το σχόλιο εμφανίζεται μετά τον κώδικα της SQL
Η σύνταξη της Transact-SQL υποστηρίζει επίσης εναλλακτικούς τρόπους μορφοποίησης για τον ορισμό σχολίων. Μια μορφή αυτής της σύνταξης είναι ίδια με το στυλ "ενότητα σχολίων" που χρησιμοποιείται στη σύνταξη της C++ και της Java.
/*
Γραμμή σχολίου 1
Γραμμή σχολίου 2
*/
SELECT COUNT(*)
       FROM Authors

OCaml 
Η OCaml χρησιμοποιεί σχόλια που μπορούν να περιέχονται σε άλλα σχόλια, κάτι που είναι χρήσιμο για το σχολιασμό μιας ενότητας κώδικα.
γραμμή με κώδικα (* σχόλιο επιπέδου 1(*σχόλιο επιπέδου 2*)*)

Σημειώσεις και παραπομπές

Εξωτερικοί σύνδεσμοι 
 Πώς να γράφετε σχόλια του Denis Krukovsky 
 Πώς να γράφετε σχόλια για το εργαλείο Javadoc 
 Doxygen, σύστημα τεκμηρίωσης για τη C, τη C++, τη Java, την Objective-C, την Python, την IDL και σε κάποιο βαθμό για την PHP, τη C#, και τη D 

Γλώσσες προγραμματισμού