Σχόλια σε

Σχετικά με την έννοια Σχόλια

Τα σχόλια σου επιτρέπουν να αφήνεις σημειώσεις στον κώδικα χωρίς να επηρεάζεται το πώς εκτελείται. Ένα σχόλιο μίας γραμμής ξεκινά με // οπουδήποτε μέσα σε μια γραμμή. Ο μεταγλωττιστής αγνοεί ό,τι βρίσκεται από το // μέχρι το τέλος αυτής της γραμμής. Όταν ένα σχόλιο έρχεται μετά από κώδικα στην ίδια γραμμή, συχνά ονομάζεται ενσωματωμένο σχόλιο. Ένα σχόλιο πολλών γραμμών ξεκινά με /* και τελειώνει με */ οπουδήποτε μέσα σε μια γραμμή. Ο μεταγλωττιστής αγνοεί ό,τι βρίσκεται ανάμεσά τους, σε μία ή περισσότερες γραμμές.

// This is a single-line comment on its own line

x := 1 // This is an single-line comment inline with code
fmt.Println(x) // prints 1

/*
This is a valid
multiline comment.
*/

/* This is also a valid multi-line comment. */

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

Σχόλια κώδικα

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

results = results[1:] // skipping the header row

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

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

Τα σχόλια τεκμηρίωσης χρησιμοποιούνται για να τεκμηριώσουν ένα πακέτο, μια μεταβλητή ή μια συνάρτηση. Αυτή η τεκμηρίωση προορίζεται για άλλους προγραμματιστές που θα ήθελαν να μάθουν πώς να χρησιμοποιήσουν τον κώδικά σου. Θα πρέπει να εξηγεί, σε γενικές γραμμές, τι κάνει ο κώδικας και πώς να τον χρησιμοποιήσεις. Δεν θα πρέπει να περιλαμβάνει λεπτομέρειες για το πώς λειτουργεί ο ίδιος ο κώδικας. Τα σχόλια τεκμηρίωσης βρίσκονται ακριβώς πριν από μια δήλωση, χωρίς κενή γραμμή να χωρίζει το σχόλιο από τη δήλωση. godoc τα αναλύει για να παράγει τεκμηρίωση πακέτου, όπως φαίνεται στο pkg.go.dev. Ένα σχόλιο τεκμηρίωσης θα πρέπει να είναι μια πλήρης πρόταση που ξεκινά με το όνομα του αναγνωριστικού και τελειώνει με τελεία.

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

Τα σχόλια που τεκμηριώνουν πακέτα ξεκινούν με το όνομα του πακέτου και περιγράφουν τι κάνει το πακέτο:

// Package kelvin provides tools to convert temperatures to and from Kelvin.
package kelvin

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

// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
    return 0
}

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

// TemperatureFahrenheit represents a certain temperature in degrees Fahrenheit.
var TemperatureFahrenheit float64

Για την πλήρη προδιαγραφή των σχολίων τεκμηρίωσης, δες τον οδηγό τεκμηρίωσης της Go.