Documentar el código es esencial. C#


Siempre que realizamos un nuevo proyecto ya sea con Visual Studio Studio y C# o cualquier otra herramienta, debemos tener en cuenta que normalmente pensamos en crear estos proyectos para que sean usados un tiempo prudencial, a veces incluso años. Por esto necesariamente el código va a ser releído muchas veces por nosotros y probablemente por otras personas. Si hemos documentado bien el código la siguiente vez que lo leamos vamos a comprender fácilmente que queríamos hacer allí, de lo contrario nos toca hacer un trabajo fuerte de reentender para que escribimos dicho código. Es por esto que se hace fundamental hacer una buena documentación.

Usando Visual Studio y C# la forma sencilla de documentar cada función, clase o programa es pulsar 3 veces la tecla slash “/” encima del nombre de la entidad respectiva y aparece una documentación sencilla:

        /// <summary>

        ///

        /// </summary>

        public int MyProperty { get; set; }

Dentro de summary ponemos una descripción clara de lo que realiza la entidad y con eso podemos darle una idea de para que sirve.

Si queremos algo más especializado debemos utilizar una herramienta que ayude a documentar, por ejemplo el GhostDoc http://submain.com/products/ghostdoc.aspx ampliamente recomendado por la comunidad de desarrolladores de VS.

Se puede bajar de la dirección mencionada arriba y una vez instalado, procedemos a documentar la misma porción de código usando clic derecho sobre el nombre de la entidad, escogemos “Document this” nueva opción creada por Ghostdoc y este es el resultado:

        /// <summary>

        /// Gets or sets my property.

        /// </summary>

        /// <value>

        /// My property.

        /// </value>

        public int MyProperty { get; set; }

Esto nos proporciona una presentación más completa y con más sentido para documentar. Esta herramienta nos va a servir mucho para usar diariamente. La recomiendo para que los programas estén más entendibles y puedan ser mejor administrados.

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s