Introducción
En el ejercicio anterior vimos que hay dos formas de escribir comentarios en Go: los comentarios de una sola línea, precedidos por //, y los bloques de comentarios de varias líneas, encerrados entre /* y */.
Comentarios de documentación
En Go, los comentarios desempeñan un papel importante a la hora de documentar el código.
Los utiliza el comando godoc, que extrae estos comentarios para crear documentación sobre los paquetes de Go.
Un comentario de documentación debe ser una oración completa que empiece por el nombre de lo que se describe y termine en punto.
Los comentarios deben preceder tanto a los paquetes como a los identificadores exportados, por ejemplo funciones exportadas, métodos, variables de paquete, constantes y structs, sobre los que aprenderás más en los próximos ejercicios.
Una variable a nivel de paquete puede tener este aspecto:
// TemperatureCelsius represents a certain temperature in degrees Celsius.
var TemperatureCelsius float64
Comentarios de paquete
Los comentarios de paquete deben escribirse justo antes de una cláusula de paquete (package x) y empezar por 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 por el nombre de la función.
Por ejemplo, un comentario exportado para 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 devueltos:
// 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 su previsión meteorológica.
Como eres un desarrollador reconocido, responsable y competente, te pidieron que escribieras un programa capaz de predecir la condición meteorológica actual de varias ciudades de Goblinocus.
En ese momento estabas ocupado y le pediste a uno de tus amigos que hiciera el trabajo en tu lugar.
Al cabo de un rato, el presidente de Goblinocus se puso en contacto contigo y te dijo que no entendía el código de tu amigo.
Cuando revisas el código, descubres que tu amigo no actuó como un desarrollador 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 listos como tú, olvidaron lo que el paquete debería hacer por ellos.
Escribe un comentario para package weather que describa su contenido.
El comentario del paquete debe presentar el paquete y proporcionar 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 comentarios para destruir su país.
Aclara el uso de las variables del paquete CurrentCondition y CurrentLocation y tranquiliza al presidente.
Esto debería indicar a cualquier usuario del paquete qué información almacenan las variables y qué puede hacer con ella.
3. Documenta la función Forecast()
Los operadores de previsión de Goblinocus quieren saber qué hace la función Forecast() (pero no les digas cómo funciona, porque, por desgracia, se confundirán aún más).
Escribe un comentario para esta función que describa qué hace la función, pero no cómo lo hace.
Ejercicio de aprendizaje
