Muchos de nosotros hemos creado clases que realizan una u otra funcionalidad, pero alguna vez pensamos en hacer que nuestras clases sean lo mas descriptivas que sea posible, para los que las utilicen conozcan o sepan lo que hace o para que sirve cada metodo o propiedad que expongamos en nuestra interfaz, por medio del intellisense cuando se escribe codigo. De esta forma:

No se ve bien que la clase me permita saber que puedo hacer con ella. Creo que algunos no pensamos en esto, este un detalle que muchos descuidamos al momento de crear nuestras clases.
Veamos como podemos hacer que nuestras clases se autodescriban asi mismas por decirlo de una forma.

Vamos a describir la siguiente clase:

using System;

namespace DescripcionClases
{
    public class Libro
    {
        string strNombre;
        int intCodigo;

        public readonly string Nombre
        {
            get
            {
                return strNombre;
            }
        }

        public void Prestamo(string NombreLibro)
        {
        }

        public void Prestamo(string NombreLibro,int CodigoLibro)
        {
        }
    }
}

Una clase libro con dos atributos y 1 metodo sobrecargado 2 veces.
Vamos a utilizar la etiqueta <summary></summary> que nos va a permitir asignarle la descripcion que queremos que salga en el intellisense,cuando visualizemos a nuestra clase.
Antes de la declaracion de la clase Libro colocamos las etiquetas summary con la descripcion que queremos que se vea, de esta forma:

/// <summary>
/// Clase para manejar libros.
/// </summary>
public class Libro

Cuando busquemos la clase Libro en el intellisense, aparecera con la descripcion que pusimos entre las etiquetas summary

La etiqueta summary no solamente nos sirve para describir clases, sino tambien propiedades y metodos que expongamos. Al igual que hicimos con la declaracion de clase Libro antes de declarar el property asignamos la descripcion respectiva, de esta forma:

/// <summary>
/// Retorna el nombre de un libro
/// </summary>
public readonly string Nombre

Cuando busquemos la propiedad Nombre en el intellisense, aparecera con la descripcion que pusimos entre las etiquetas summary

Ahora viene lo mas interesante, tenemos un metodo Prestamo sobrecargado dos veces y ademas recibe parametros, asignamos la descripcion respectiva como en los casos anteriores, estariamos describiendo el metodo mas no los parametros, de esta forma:

/// <summary>
/// Procesa el prestamo del libro
/// </summary>
public void Prestamo(string NombreLibro)

y tambien para el otro, asi:

/// <summary>
/// Procesa el prestamo del libro el primer libro
/// </summary>
public void Prestamo(string NombreLibro,int CodigoLibro)

Cuando busquemos la propiedad Nombre en el intellisense, solo aparecera con la descripcion del metodo, asi:

Ahora tenemos que describir los parametros que recibe cada metodo, para esto utlizaremos la etiqueta <param></param>, que tiene un atributo name en donde se coloca el nombre del parametro a describir,y entre estas dos etiquetas se coloca la descripcion de dicho parametro, entonces quedaria de esta forma:

/// <summary>
/// Procesa el prestamo del libro
/// </summary>
/// <param name="NombreLibro"> Nombre del libro a prestar</param>
public void Prestamo(string NombreLibro)

Y para el otro metodo que tiene dos parametros , quedaria asi:

/// <summary>
/// Procesa el prestamo del libro el primer libro
/// </summary>
/// <param name="NombreLibro"> Nombre del libro a prestar</param>
/// <param name="CodigoLibro"> Codigo del libro a prestar</param>
public void Prestamo(string NombreLibro,int CodigoLibro)

Cuando busquemos la metodo Prestamo en el intellisense, aparecerá el metodo sobrecargado con sus parametros indicando la descripcion, asi:

Notese que las descripciones que salen son como la de cualquier otra clase en .NET

Conclusiones.

Describir nuestras clases permite que nuestras clases sean mas entendibles, ya que se estara describiendo cada elemento de nuesta intefaz.Esto facilita la tarea de otros desarrolladores en el momento que quieran utilizar estas clases. Recuerden en cuanto mejor sea la descripcion que hagamos de nuestra clase, mejor va a ser el uso que le den otros usuarios a nuestras clases, porque van a saber que estan utilizando o que estan obteniendo, aumentando su productividad al momento de desarrollar.
...

 

---

Espacios de nombres usados en el código de este artículo:

System

Fichero con el código de ejemplo: juanpe_DescripcionClases.zip - 6 KB