Saltar al contenido
Menú
El blog de Kañaz
  • Inicio
  • Acerca de
  • Github
  • Youtube
  • LinkedIn
  • Twitter
El blog de Kañaz

Día 10: Comentarios y descripciones

Publicada el 28 julio, 201228 julio, 2012
Twittear

dia10

Este post es demasiado sencillo, pero recuerda que en la sencillez de los detalles puede radicar la grandeza de tu aplicación, así que es bueno que lo consideres para tus proyectos.

Comentarios

No escribas comentarios por cada línea, método, variable y propiedad creados.

Utiliza // o /// para los comentarios. Evita el uso de  /* … */

Escribe comentarios cuando sea requerido. Pero entre mejor sea tu código, menos comentarios deberá llevar. En los días anteriores puedes ver como lograr nombres adecuados para tus elementos declarados.

No escribas líneas de comentarios si tu código se puede entender de forma “automática”.

Si escribiste ya un comentario y por cualquier razón actualizaste tu código, recuerda actualizar tus comentarios, un mal comentario puede llevar a mas confusión que uno inexistente.

Menos líneas de comentarios, harán tu código mas “elegante”. Pero en caso de que alguna parte de código sea demasiado confusa, entonces debes poder colocar tantos como sea necesario.

La anterior nos lleva a esta parte, si tienes un fragmento de código que por cualquier razón sea muy especializado (o simplemente complicado) documéntalo muy bien de ser necesario con una línea de comentarios por línea de código.

Si inicializas una variable numérica con un valor especial como (0, –1 o el que quieras). Debes explicar porqué escogiste tal valor.

El objetivo ideal es llegar a tener tanta práctica estructurando, nombrando y escribiendo todo tu código de una forma tan comprensible que no debas tener la necesidad de escribir comentarios para poder entenderlo.

Cuida tu ortografía y gramática en tus líneas de comentarios, recuerda que debes demostrar estar a la altura de un nivel profesional tanto en tus líneas de código como en tus comentarios.

Etiquetas

Al momento de invocar un método, puedes recibir toda la información que necesites a partir de sus datos de documentación.

Descripcion1

 

Descripcion2

Y en cambio si se trata de uno de tus métodos, el resultado es este.

DescripcionPropia

Para eliminar esa diferencia, al crear un método, puedes insertarle su propia documentación con solo presionar /// te aparecerá el tag de summary, la documentación necesaria será en formato XML.

Summary

Y el resultado es el siguiente.

DescripcionPropia2

Como puedes notar, es muy sencillo poder crear la documentación de tus métodos, para complementar esta parte de etiquetas, puedes considerar lo siguiente.

<summary> : El contenido de la explicación del método. Puedes leer un poco mas aquí.

<remarks> : Comentarios especiales, solo visibles dentro de la documentación, pero no visibles con Intellisense.

<return> : Explica el valor devuelto por la función.

<param> : Se utilizan para describir cada uno de los parámetros del método o la función. Puedes usar su atributo paramref para establecer relevancia.

<example> : Lo utilizas para colocar un ejemplo de como usar tu elemento.

<permision> : Indica que tipo de permiso necesita tu elemento. Puedes usar su atributo cref para indicar el tipo que representa a ese permiso.

DocumentacionCompleta

Generar la documentación

Ya que todo tu proyecto tiene la todo lo necesario para poder crear un buen documento, solo debes ir a las propiedades de tu proyecto y elegir la pestaña Build y después seleccionar el checkBox de un archivo de documentación.

DocumentacionConfiguracion

Y el resultado será un archivo XML con toda tu documentación.

DocumentoDocumentacion

Conclusión

¿Te imaginas hacer una aplicación para leer este archivo? Imagina lo bien que quedarías con tu cliente si le entregas tu documentación con una aplicación y no un simple PDF. Si la haces ¡nos harías muy felices a muchos al publicarla!

Deja una respuesta Cancelar la respuesta

Tu dirección de correo electrónico no será publicada. Los campos obligatorios están marcados con *

Busca en este sitio

MI perfil de Github

Github profile

Sígueme en Twitter

Seguir a @aminespinoza
©2023 El blog de Kañaz | Funciona con SuperbThemes y WordPress