Εισαγωγή
Στην προηγούμενη άσκηση, είδαμε ότι υπάρχουν δύο τρόποι να γράψεις σχόλια στη Go: σχόλια μίας γραμμής όπου προηγείται το // και μπλοκ σχολίων πολλών γραμμών που περικλείονται με /* και */.
Σχόλια τεκμηρίωσης
Στη Go, τα σχόλια παίζουν σημαντικό ρόλο στην τεκμηρίωση του κώδικα.
Χρησιμοποιούνται από την εντολή godoc, η οποία εξάγει αυτά τα σχόλια για να δημιουργήσει τεκμηρίωση για πακέτα Go.
Ένα σχόλιο τεκμηρίωσης πρέπει να είναι μια πλήρης πρόταση που ξεκινά με το όνομα του πράγματος που περιγράφεται και τελειώνει με τελεία.
Τα σχόλια πρέπει να προηγούνται των πακέτων καθώς και των εξαγόμενων αναγνωριστικών, για παράδειγμα εξαγόμενες συναρτήσεις, μέθοδοι, μεταβλητές πακέτου, σταθερές και structs, για τα οποία θα μάθεις περισσότερα στις επόμενες ασκήσεις.
Μια μεταβλητή σε επίπεδο πακέτου μπορεί να μοιάζει κάπως έτσι:
// TemperatureCelsius represents a certain temperature in degrees Celsius.
var TemperatureCelsius float64
Σχόλια πακέτου
Τα σχόλια πακέτου πρέπει να γράφονται ακριβώς πριν από μια ρήτρα πακέτου (package x) και να ξεκινούν με Package x ... ως εξής:
// Package kelvin provides tools to convert
// temperatures to and from Kelvin.
package kelvin
Σχόλια συναρτήσεων
Ένα σχόλιο συνάρτησης πρέπει να γράφεται ακριβώς πριν από τη δήλωση της συνάρτησης.
Πρέπει να είναι μια πλήρης πρόταση που ξεκινά με το όνομα της συνάρτησης.
Για παράδειγμα, ένα εξαγόμενο σχόλιο για τη συνάρτηση Calculate πρέπει να έχει τη μορφή Calculate ....
Πρέπει επίσης να εξηγεί ποια ορίσματα δέχεται η συνάρτηση, τι κάνει με αυτά και τι σημαίνουν οι τιμές επιστροφής της, και να τελειώνει με τελεία:
// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
return 0
}
Οδηγίες
Το Goblinocus είναι μια χώρα που παίρνει την πρόγνωση του καιρού πολύ στα σοβαρά.
Επειδή είσαι ένας φημισμένος, υπεύθυνος και ικανός προγραμματιστής, σου ζήτησαν να γράψεις ένα πρόγραμμα που να προβλέπει την τρέχουσα καιρική κατάσταση διάφορων πόλεων στο Goblinocus.
Εκείνη την εποχή ήσουν απασχολημένος και ζήτησες από έναν φίλο σου να κάνει τη δουλειά αντ' αυτού.
Μετά από λίγο, ο πρόεδρος του Goblinocus επικοινώνησε μαζί σου και σου είπε ότι δεν καταλαβαίνουν τον κώδικα του φίλου σου.
Όταν ελέγχεις τον κώδικα, ανακαλύπτεις ότι ο φίλος σου δεν ενήργησε σαν υπεύθυνος προγραμματιστής και ότι δεν υπάρχουν σχόλια στον κώδικα.
Νιώθεις υποχρεωμένος να αποσαφηνίσεις το πρόγραμμα ώστε να μπορούν να το καταλάβουν και τα γκόμπλιν.
1. Τεκμηρίωσε το πακέτο weather
Επειδή τα γκόμπλιν δεν είναι τόσο έξυπνα όσο εσύ, ξέχασαν τι πρέπει να κάνει το πακέτο γι' αυτά.
Γράψε ένα σχόλιο για το package weather που να περιγράφει το περιεχόμενό του.
Το σχόλιο του πακέτου θα πρέπει να παρουσιάζει το πακέτο και να δίνει πληροφορίες που αφορούν το πακέτο ως σύνολο.
Ο πρόεδρος του Goblinocus είναι λίγο παρανοϊκός και φοβάται ότι χρησιμοποιούνται μεταβλητές χωρίς σχόλια για να καταστρέψουν τη χώρα τους.
Διευκρίνισε τη χρήση των μεταβλητών του πακέτου CurrentCondition και CurrentLocation και καθησύχασε τον πρόεδρο.
Αυτό θα πρέπει να λέει σε κάθε χρήστη του πακέτου ποιες πληροφορίες αποθηκεύουν οι μεταβλητές και τι μπορεί να κάνει με αυτές.
3. Τεκμηρίωσε τη συνάρτηση Forecast()
Οι χειριστές των προβλέψεων του Goblinocus θέλουν να μάθουν τι κάνει η συνάρτηση Forecast() (αλλά μην τους πεις πώς λειτουργεί, γιατί δυστυχώς θα μπερδευτούν ακόμα περισσότερο).
Γράψε ένα σχόλιο για αυτή τη συνάρτηση που να περιγράφει τι κάνει η συνάρτηση, αλλά όχι πώς το κάνει.
Άσκηση εκμάθησης
