Introducción
En el ejercicio anterior vimos que hay dos formas de escribir comentarios en Go: los comentarios de una sola línea, que van precedidos de //, y los bloques de comentarios de varias líneas, que se delimitan con /* y */.
Comentarios de documentación
En Go, los comentarios cumplen un papel importante en la documentación del código.
Los usa el comando godoc, que extrae esos comentarios para crear documentación sobre los paquetes de Go.
Un comentario de documentación debe ser una oración completa que empiece con el nombre de lo que se describe y termine con un punto.
Los comentarios deben ir antes de los paquetes y también de los identificadores exportados, por ejemplo las funciones, los métodos, las variables de paquete, las constantes y los structs exportados, sobre los cuales aprenderás más en los próximos ejercicios.
Una variable a nivel de paquete puede verse así:
// TemperatureCelsius represents a certain temperature in degrees Celsius.
var TemperatureCelsius float64
Comentarios de paquete
Los comentarios de paquete deben escribirse justo antes de la cláusula del paquete (package x) y empezar con Package x ..., así:
// Package kelvin provides tools to convert
// temperatures to and from Kelvin.
package kelvin
Comentarios de función
Un comentario de función debe escribirse justo antes de la declaración de la función.
Debe ser una oración completa que empiece con el nombre de la función.
Por ejemplo, el comentario exportado de la función Calculate debe tener la forma Calculate ....
También debe explicar qué argumentos recibe la función, qué hace con ellos y qué significan sus valores de retorno, y terminar con un punto):
// CelsiusFreezingTemp returns an integer value equal to the temperature at which water freezes in degrees Celsius.
func CelsiusFreezingTemp() int {
return 0
}
Instrucciones
Goblinocus es un país que se toma muy en serio el pronóstico del clima.
Como eres un desarrollador reconocido, responsable y competente, te pidieron que escribieras un programa capaz de pronosticar la condición climática actual de varias ciudades de Goblinocus.
En ese momento estabas ocupado, así que le pediste a uno de tus amigos que hiciera el trabajo en tu lugar.
Al poco tiempo, el presidente de Goblinocus se comunicó contigo y te dijo que no entiende el código de tu amigo.
Cuando revisas el código, descubres que tu amigo no actuó como un programador responsable y que no hay comentarios en el código.
Te sientes en la obligación de aclarar el programa para que los goblins también puedan entenderlo.
1. Documenta el paquete weather
Como los goblins no son tan inteligentes como tú, olvidaron qué debería hacer el paquete por ellos.
Escribe un comentario para package weather que describa su contenido.
El comentario del paquete debería presentar el paquete y brindar información relevante para el paquete en su conjunto.
2. Documenta las variables CurrentCondition y CurrentLocation
El presidente de Goblinocus es un poco paranoico y teme que se usen variables sin comentar para destruir su país.
Aclara el uso de las variables del paquete CurrentCondition y CurrentLocation y deja tranquilo al presidente.
Esto debería indicarle a cualquiera que use el paquete qué información guardan las variables y qué puede hacer con ella.
3. Documenta la función Forecast()
Los encargados de los pronósticos en Goblinocus quieren saber qué hace la función Forecast() (pero no les digas cómo lo hace, porque, por desgracia, se confundirían aún más).
Escribe un comentario para esta función que describa qué hace, pero no cómo lo hace.
Ejercicio de aprendizaje
