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.
Y en cambio si se trata de uno de tus métodos, el resultado es este.
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.
Y el resultado es el siguiente.
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.
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.
Y el resultado será un archivo XML con toda tu documentación.
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!