Cuando piensa en programación, es natural centrarse en temas como lenguajes, algoritmos y depuración. Pero la documentación técnica puede ser igual de importante para hacerlo bien.
Sin una buena documentación, la reutilización del código puede verse afectada. Los usuarios nuevos en una base de código pueden perderse o frustrarse fácilmente si la documentación no está a la altura. No solo es importante comprender lo que hace un programa, sino también cómo, o incluso por qué, lo hace.
Paquetes como Pydoc para Python y Javadoc para Java ayudan al automatizar parte del proceso. La herramienta Godoc hace lo mismo para Go.
¿Qué es Godoc?
Godoc es un paquete de Go que le permite crear, administrar y usar la documentación de Go al estilo Go. El método Go es un conjunto de principios que, como programador de Go, debe seguir para mejorar la calidad del código.
Usando Godoc, puede leer fácilmente la documentación y el código de otros desarrolladores. También puedes automatizar la creación de tu propia documentación y publicarla usando Godoc.
Godoc es similar a Javadoc, el documentador de código para Java. Ambos usan comentarios y código en módulos para generar documentación. Y ambas herramientas estructuran esa documentación en HTML para que puedas verla en un navegador.
Primeros pasos con Godoc
Usar Godoc es fácil. Para comenzar, instale el paquete Godoc desde el sitio web de golang usando este comando:
Vamos obtener golang.org/x/tools/cmd/godoc
Ejecutar este comando instalará Godoc en su espacio de trabajo especificado. Una vez que se complete, debería poder ejecutar el godoc comando en una terminal. Si hay algún error con su instalación, intente actualizar Go a una versión más reciente.
Godoc busca comentarios de una o varias líneas para incluirlos en la documentación que genera.
Asegúrese de formatear el código de la manera Go, como se explica en la publicación Go Efectivo por el equipo Go para obtener los mejores resultados.
Aquí hay un ejemplo usando comentarios de una sola línea al estilo de C++:
// El usuario es un modelo de estructura que contiene
escribe Usuario estructura {
}
También puede usar comentarios de bloque de estilo C:
/*
El usuario es una estructura de datos personalizadaPuede incluir cualquier texto aquí y el servidor Godoc lo formateará cuando lo ejecute.
*/
escribe Usuario estructura {
}
En los comentarios anteriores, "Usuario" comienza las oraciones porque el comentario describe lo que hace la estructura del Usuario. Este es uno de los muchos temas que trata el método Go. Comenzar las oraciones de documentación con un nombre útil es crucial ya que la primera oración aparece en la lista de paquetes.
Ejecutar un servidor Godoc
Una vez que haya comentado su código, puede ejecutar el godoc comando en su terminal, desde el directorio de código de su proyecto.
Convencionalmente, los desarrolladores de Go usan port 6060 para alojar la documentación. Este es el comando para ejecutar un servidor Godoc en ese puerto:
godoc-http=:6060
El comando anterior alberga la documentación de su código en servidor local, o 127.0.0.1. El puerto no tiene que ser 6060; godoc se ejecutará en cualquier puerto desocupado. Sin embargo, siempre es mejor seguir las convenciones de la documentación de Go.
Una vez que haya ejecutado el comando, puede ver su documentación en un navegador visitando servidor local: 6060. El tiempo que tarda Godoc en generar tu documentación dependerá de su tamaño y complejidad.
El siguiente código se adhiere a la forma Go, en este caso usando comentarios de una sola línea.
// nombre del paquete
paquete usuario// fmt es responsable del formato
importar (
"fmt"
)// El usuario es una estructura de datos humanos
escribe Usuario estructura {
Años En t
Nombre cuerda
}funciónprincipal() {
// humano es una inicialización de la estructura de Usuario
humano := Usuario {
Años: 0,
Nombre: "persona",
}fmt. Imprimir (humano. Hablar())
}
// Talk es un método de la estructura User
función(Usuario receptor)Hablar()cuerda {
devolver "¡Todos los usuarios pueden decir algo!"
}
Si ejecuta Godoc en el módulo de código anterior, debería ver un resultado similar a este:
Tenga en cuenta que está en un formato familiar, similar al que encontrará en el sitio web de documentación oficial de Go.
Godoc usa el comentario que precede a la declaración del paquete como el Visión general. Asegúrese de que este comentario describa lo que hace su programa.
los Índice contiene enlaces a las declaraciones de tipos y métodos para que pueda navegar hasta ellos rápidamente.
Godoc también proporciona funcionalidad para ver el código fuente que compone el paquete en el Paquete de archivos sección.
Mejorando su documentación usando Godoc
Puede incluir más que solo texto sin formato en su documentación de Godoc. Puede agregar URL para las que Godoc generará enlaces y estructurará sus comentarios en párrafos.
Si desea vincular a un recurso, escriba la URL en su comentario y Godoc lo reconocerá y agregará un enlace. Para los párrafos, deje una línea de comentario vacía.
// Paquete principal
paquete principal// El documento representa un documento normal.
//
// Enlace a https://google.com
escribe Documento estructura {
paginas En t
referencias cuerda
firmado bool
}// Write escribe un nuevo documento en el almacenamiento
//
// Puedes aprender sobre escritura en Wikipedia.com
funciónEscribe() {
}
Tenga en cuenta que Godoc requiere que escriba las URL en su totalidad para poder vincularlas. En este ejemplo, la URL de Google incluye el https:// prefijo, por lo que Godoc le agrega un enlace. Dado que el dominio de Wikipedia no es una URL completa por sí solo, Godoc lo dejará en paz.
Estos son algunos de los mejores principios para aplicar al documentar su código Go:
- Mantenga su documentación simple y concisa.
- Comience la oración de funciones, tipos y declaraciones de variables por sus nombres.
- Comience una línea con una sangría para formatearla previamente como código.
- Los comentarios que comienzan con "ERROR(nombre)" como "ERROR(joe): Esto no funciona" son especiales. Godoc los reconocerá como errores y los informará en su propia sección de la documentación.
Godoc puede aliviar sus problemas de documentación
Usando Godoc, puede ser más productivo y preocuparse menos por el esfuerzo de documentar sus programas a mano.
Debe mantener su documentación precisa, detallada y precisa para que sea más fácil de leer y comprender para su público objetivo. También es vital que mantenga actualizados los comentarios del código a medida que modifica su programa.
Consulte la documentación del paquete Godoc para obtener más información sobre el uso de Godoc.
