Documentando los proyectos .NET con Sandcastle
Siempre que programamos nos deberíamos encontrar con la necesidad de documentar nuestros proyectos de manera que tengamos una documentación asociada al proyecto y lo más cerca de nuestras manos.
Separando los análisis de requerimientos o los diseños técnicos a un lado por poner dos tipos de documentos esenciales en todo proyecto, la documentación más frecuente para un programador son los ficheros de ayuda.
No me refiero a los ficheros de ayuda de usuario, sino a los ficheros de ayuda de desarrollo y programación.
Evidentemente (y no debemos olvidarlo nunca), hay siempre un coste asociado al tiempo dedicado por un programador a la codificación y que no está estrechamente ligado con las instrucciones de código, son los comentarios de código.
En muchas empresas no se entiende esta labor de documentación como una inversión que aporte beneficio para el desarrollo empresarial, sino como un gasto.
A la larga, muchas de esas empresas terminan gastando más dinero en tratar de entender cómo funcionaba una parte del código que en ir directamente a un fichero de ayuda, leerlo y comprenderlo de forma efectiva y rápida.
Pero no sólo con un fichero de ayuda nos basta, también tenemos que tener claro que el fichero de ayuda debe estar bien cumplimentado, y eso se hace desde el código y en el caso de .NET con los comentarios XML.
Sin embargo, para generarlos debemos tener claras varias pautas.
Por un lado que documentar el código es una tarea MUY importante. Escribir comentarios como «Esto es una clase» no nos aporta ningún valor adicional. A veces las prisas nos lleva a escribir este tipo de comentarios, pero casi mejor no poner nada a poner algo que no nos aporta valor.
Lo ideal y recomendado es comentar al mismo tiempo que se programa. De esa manera nunca dejaremos nada en el cajón del recuerdo y haremos las cosas a un mismo ritmo y con la idea fresca de lo que se escribe.
Sé que hay gente que opina que si el código está lo suficientemente bien hecho no es necesario escribir apenas comentarios, sin embargo (y es una opinión muy personal), no estoy nada de acuerdo con esta afirmación. Los proyectos cambian, avanzan, y las personas que trabajan con un proyecto también, por lo que los comentarios son más que recomendables,… casi diria obligados.
De los anteriores puntos se desprende que los comentarios deben obviamente aportarnos valor. En caso contrario, los comentarios de código no sirven de nada.
Es obvio no obstante, que al iniciar un proyecto debemos preparar una documentación de estilos de documentación que se utilice a lo largo de todas y cada una de las fases y de las clases que forman parte del proyecto.
Cabeceras, comentarios tipo, referencias, ejemplos, etc.
También sé que los comentarios no se compilan, y que por lo tanto, no dan un valor añadido directo al ensamblado, módulo o codificación en cuestión, sin embargo, sí otorga un papel relevante y un beneficio indirecto que es muy importante tener en consideración y que es el que muchos obvian.
En Internet podemos encontrar mucha documentación sobre como escribir nuestros comentarios Xml en .NET.
Sirva como material de apoyo el siguiente documento Word.
Y llegados a este punto, ¿qué Software tenemos para ayudarnos a documentar nuestros proyectos?.
A mí me encanta uno de ellos llamado Document! X de Innovasis.
Sin embargo, tendremos que tener en cuenta su coste que asciende a 357€ para 1 usuario.
Si no nos queremos rascar el bolsillo, entonces podremos irnos a una solución gratuita, con muchas menos cosas que las que nos ofrece Document! X, pero que nos puede sacar del lío.
Me refiero a Sandcastle.
Sandcastle era un proyecto que nos ayudaba a documentar nuestros ensamblados, sin embargo, el proyecto parecía haberse quedado muerto hasta el pasado mes de Junio, en el que la gente de Sandcastle actualizó su producto.
Sin embargo, la instalación real requiere tres acciones que paso a enumerar una a una:
1) La primera de todas es que debemos descargarnos el HTML Help Workshop and Documentation de Microsoft.
Allí encontraremos un fichero de nombre htmlhelp.exe y de 3.3 Mb.
Descargaremos el fichero y lo instalaremos en la máquina cliente.
2) La segunda acción es instalar Sandcastle – Documentation Compiler for Managed Class Libraries.
El proyecto está en Codeplex y su última versión es del pasado 23 de Junio de 2010 (v2.6.1062.1).
Descargaremos el fichero sandcastle.msi de casi 15 Mb y lo instalaremos en la máquina cliente.
3) La tercera acción es instalar Sandcastle Help File Builder.
Este proyecto está también en CodePlex y los permite trabajar con una interfaz gráfica realmente cómoda para indicar qué ensamblados queremos documentar en fichero de ayuda, así como las referencias de los ensamblados y otras características.
La versión última es la v1.9.1.0 de fecha 7 de Julio de 2010.
El fichero Sandcastle Help File Builder Installer de casi 9 Mb nos permitirá instalar la interfaz de usuario que trabaja con Sandcastle Documentarion Compiler for Managed Class Libraries comentado en el punto 2.
Una vez concluida la instalación de estos paquetes, te recomiendo reiniciar el equipo para evitar sorpresas.
Con estas acciones, podremos preparar con Sandcastle Help File Builder un proyecto de compilación de ayuda, indicar los ensamblados que queremos documentar y ejecutar el compilador de ayudas.
El proceso tarda un rato, pero nos generará un log de mensajes de error, warning e información, además de compilar el fichero de ayuda.
Allí podremos repasar igualmente si faltan comentarios en los ficheros de ayuda, si hay comentarios mal escritos, etc.
8 Responsesso far
Como aporte, comentar que existe el plugin gratuito GhostDoc para Visual Studio que nos ayuda a generar los comentarios XML.
Se puede descargar de aqui:
http://submain.com/products/ghostdoc.aspx
Saludos.
Muchas gracias por tu aporte dagope.
Hace unos 3 años que no utilizo este plugin y veo que lo han actualizado.
Miraré a ver si aporta alguna ventaja más que eché en falta en su día.
¡Muchas gracias por comentar! (se agradece). 🙂
Justo iba a hacer el mismo comentario dagope, yo lo uso junto con ghostdoc y ayuda mucho.
bueno, ya de paso pongo yo también mi granito de arena, http://sandcastlestyles.codeplex.com/ unos cuantos estilos más para las documentaciones generadas, el «hana» es el que más utilizo.
Útil para hacer el manual técnico, ¿algo para el manual de usuario?
Hace un par de años intenté utilizar el Sandcastle y me pareció todo muy complicado y rocambolesco… si es tan importante la documentación, ¡¿por qé no está integrada alguna herramienta de generación de documentación en el propio VS?!
Espero que pase lo mismo que ya pasó con los test unitarios (yo utilizaba NUnit antes de que estuvieran integrados). Pero me parece raro que tarden tanto.
@Lentucky
Si quieres hacer manual de usuario «al estilo msdn», es decir con enlaces a la documentación generada por SandCastle y con el mismo estilo, lo puedes hacer usando el propio SandCastle. SandCastle admite un tipo de archivos en XML (llamados MAML). Estos archivos se integran en el proyecto de SandCastle y mediante tags especiales pueden tener enlaces a la documentación de SandCastle.
Con SandCastle Help File Builder era muy fácil integrar estos archivos MAML: los añadías en el apartado de «Additional Content» creo que era y creabas un TOC (tabla de contenidos) para ellos y dicho TOC se «mezclaba» con el TOC global formado por los namespaces y sus clases.
El coñazo era que no hay (o almenos no había hace un par de años) editor visual para esos archivos MAML por lo que te tocaba teclear el XML a mano…
Aquí tienes una guia de MAML:
http://sandcastlestyles.codeplex.com/releases/view/17333
Y aquí alguien que se pregunta si existe en el mundo algún editor para MAML:
http://stackoverflow.com/questions/108429/does-anyone-know-of-a-good-maml-editor
Cuando yo estaba metido en temas de estos (hace un par de años) no había ningún editor visual, ahora veo que tampoco hay mucha cosa.
La ventaja de usar MAML es que en un mismo .chm puedes distribuir tanto la ayuda de las clases como tu «manual de usuario» (o manual del desarrollador mejor dicho :p).
Un saludo!
como habria que configuralo par que funciona con vb por que los comentarios no funcionan , gracias por la informacion
Buenos dias, ya veo que este post tiene unos añitos, pero si pudierais contestarme alguno…estaria bien. Sucede que estoy documentando un proyecto que me traigo entre manos y he empezado a utilizar esta herramienta. No es dificil utilizarla, la cuestion es que …como bien sabeis los programadores, de vez en cuando, escribirmos unos de esos trozos de codigo que no puede ponerse en una clase aparte peor que queremos encontrar rápidamente para reutilizar en otro lugar … No se si me explico. Me gustaria saber si conoceis alguna forma de marcar ese código y que despues ..al general el documento XML sandcastle lo identifique y nos muestre algo asi como un diccionario de ejemplos de código.
En fin si alguno sabe de lo que hablo y somo hacerlo…le estaria enormemente agradecido.
Saludos.