Bienvenidos sean a este post, una buena practica en programacion que nos permite Visual Studio es poder generar una documentacion de nuestro codigo.
Para hacer esto utiliza un formato XML donde por medio de tags definiremos los distintos tipos de secciones que habra para nuestro documento, su formato basico es:
/// <summary>
/// Texto va aca.
/// </summary>Como pueden observar en el ejemplo, siempre llevan primero la triple barra, luego tendremos un tag identificador, despues pondremos todo el texto que necesitemos y por ultimo cerraremos el tag, exactamente como en HTML o XML, este ejemplo es su formato mas basico, veamos a continuacion älgunos de los distintos tags que tenemos disponibles y son mas utilizados para documentar:
- summary, es para escribir un breve resumen de lo que hace la clase, metodo o propiedad donde lo usemos
- remarks, provee mas informacion de la que informamos en summary
- returns, provee la informacion de que tipo devuelve return en un metodo
- value, trabaja de forma similar a la anterior solo que usa para el valor de una propiedad
- example, se usa para dejar un ejemplo en el documento XML, su tag hijo es code
- para, se usa para dividir el texto en parrafos, suele ser hijo de remarks y returns asi como code es de example
- c, nos permite usar codigo en el documento
- exception, nos permite notificar que tipo de excepcion puede lanzar el metodo
- see, nos permite crear un vinculo para otro metodo, trabaja en conjunto con cref
- seealso, es igual a la anterior pero se usa habitualmente como complemento de see (p.e. Vea Tambien)
- param, se usa para describir los parametros de un metodo
- typeparam, se usa igual que param pero para describir tipos genericos
- paramref, igual a los dos anteriores pero permite hacer una referencia a un parametro
- typeparamref, igual al anterior pero para tipos genericos
- list, nos permite formatear la informacion del documento como una lista ordenada
- inheritdoc, permite heredar comentarios XML de clases base, interfaces y metodos similares.
Estos van a ser algunos de los tags que tendremos disponibles, para ver como trabaja vamos a tomar nuestro proyecto Alumnos de la solucion Universidad, visto en los posts anteriores, y vamos a modificar las clases de las siguientes formas:
Estudiantes.cs
using System;
using System.IO;
namespace Alumnos.Clases
{
/// <summary>
/// Esta es la clase que concede los metodos de consulta
/// a los alumnos.
/// <list type="bullet">
/// <item>
/// <term>ListarAlumnos</term>
/// <description>Listado el codigo y nombre de todos los alumnos</description>
/// </item>
/// <item>
/// <term>MostrarNotas</term>
/// <description>Devuelve las notas de un alumno.</description>
/// </item>
/// </list>
/// </summary>
/// <remarks>
/// Esta clase sirve solo para los alumnos pero comparte el metodo
/// MostrarNotas con los profesores.
/// </remarks>
public class Estudiantes
{
Inifile configuracion = new Inifile("config.ini");
string pathAlumnos;
string pathExamenes;
string pathNotas;
/// <summary>
/// <para>Este es el metodo encargado de listar el ID junto al</para>
/// <para>Nombre y Apellido de los Alumnos.</para>
/// </summary>
public void ListarAlumnos()
{
pathAlumnos = configuracion.mostrar("rutas","alumnos");
Console.WriteLine("Codigos de los alumnos: ");
using (StreamReader sr = File.OpenText(pathAlumnos))
{
string linea;
string[] s;
while ((linea = sr.ReadLine()) != null)
{
s = linea.Split(',');
Console.WriteLine(s[0] + " - " + s[2] + "," + s[1]);
}
}
Console.Write("Presiona Enter para volver al menu");
Console.ReadLine();
}
/// <summary>
/// <para>Se encarga de buscar las notas del alumno informado</para>
/// Mira <see cref="Estudiantes.ListarAlumnos()"/>si no sabes el ID del Alumno
/// </summary>
/// <returns>
/// Este metodo devuelve un listado de las notas del alumno
/// </returns>
public void MostrarNotas()
{
string alumno;
pathNotas = configuracion.mostrar("rutas", "notas");
pathExamenes = configuracion.mostrar("rutas", "examenes");
Console.Clear();
Console.Write("Ingresa el ID del alumno: ");
alumno = Console.ReadLine();
using (StreamReader sr = File.OpenText(pathNotas))
{
float total = 0;
int cuenta = 0;
string examen = "";
string linea,t;
string[] s, u;
while ((linea = sr.ReadLine()) != null)
{
s = linea.Split(',');
if (s[1] == alumno.ToUpper())
{
using(StreamReader sr2 = File.OpenText(pathExamenes))
{
while((t = sr2.ReadLine())!=null)
{
u = t.Split(',');
if (u[0] == s[0])
examen = u[1];
}
}
Console.WriteLine(s[1] + "\t" + examen + "\t" + s[2]);
total += float.Parse(s[2]);
cuenta++;
}
}
Console.WriteLine("Tu promedio es: " + (total/cuenta));
}
Console.Write("Presiona Enter para volver al menu");
Console.ReadLine();
}
}
}En este caso usaremos la documentacion para explicar para que es la clase y los distintos metodos que dispone, veamos el primer bloque de comentarios:
/// <summary>
/// Esta es la clase que concede los metodos de consulta
/// a los alumnos.
/// <list type="bullet">
/// <item>
/// <term>ListarAlumnos</term>
/// <description>Listado el codigo y nombre de todos los alumnos</description>
/// </item>
/// <item>
/// <term>MostrarNotas</term>
/// <description>Devuelve las notas de un alumno.</description>
/// </item>
/// </list>
/// </summary>
/// <remarks>
/// Esta clase sirve solo para los alumnos pero comparte el metodo
/// MostrarNotas con los profesores.
/// </remarks>En este caso mostramos un resumen de lo que hace la clase y una lista con los metodos disponibles, nuestra siguiente documentacion sera la siguiente:
/// <summary>
/// <para>Este es el metodo encargado de listar el ID junto al</para>
/// <para>Nombre y Apellido de los Alumnos.</para>
/// </summary>Esta sera para la documentacion para el metodo ListarAlumnos, donde explicaremos para que se usa, nuestra siguiente documentacion sera para el metodo MostrarNotas:
/// <summary>
/// <para>Se encarga de buscar las notas del alumno informado</para>
/// Mira <see cref="Estudiantes.ListarAlumnos()"/>si no sabes el ID del Alumno
/// </summary>
/// <returns>
/// Este metodo devuelve un listado de las notas del alumno
/// </returns>En este bloque de comentarios describimos que hace el metodo pero tambien nos ofrece una opcion de mirar otro metodo para averiguar un dato que no sepamos, con esto explicado pasemos a la siguiente clase donde haremos lo mismo:
Inifile.cs
using System;
using System.Collections.Generic;
using System.IO;
namespace Alumnos.Clases
{
/// <summary>
/// <para>Esta clase se encarga de tomar la informacion de nuestro</para>
/// <para>archivo de configuracion local, se hereda a los otros proyectos</para>
/// </summary>
public class Inifile
{
private string _archivo;
private string ComentLimit;
private Dictionary<string,string> diccionario=new Dictionary<string, string>();
/// <summary>
/// <para>Constructor que recibe el nombre del archivo de configuracion y</para>
/// <para>tambien de forma opcional el parametro que usamos para los </para>
/// <para>comentarios, sino informamos ninguno utiliza el ; como predeterminado</para>
/// </summary>
/// <param name="archivo">Un dato de tipo cadena</param>
/// <param name="comentLimit">Un caracter de tipo cadena</param>
public Inifile(string archivo, string comentLimit = ";")
{
ComentLimit = comentLimit;
elarchivo = archivo;
}
/// <summary>
/// Variable que por medio de get y set se encarga de abrir el
/// archivo, mirar su interior y en base a las instrucciones
/// que posee almacena los datos en un Diccionario.
/// </summary>
public string elarchivo
{
get
{
return _archivo;
}
set
{
_archivo = null;
if (File.Exists(value))
{
_archivo = value;
using (StreamReader sr = File.OpenText(_archivo))
{
string linea, seccion = "", clave = "", clave2 = "", valor = "";
while ((linea = sr.ReadLine()) != null)
{
if (linea.Length == 0)
continue;
if ((!String.IsNullOrEmpty(ComentLimit))
&& (linea.StartsWith(ComentLimit)))
continue;
if (linea.StartsWith("[") && linea.Contains("]"))
{
int indice = linea.IndexOf(']');
seccion = linea.Substring(1, indice - 1).Trim();
// Console.WriteLine(seccion);
}
if (linea.Contains("="))
{
int indice = linea.IndexOf('=');
clave = linea.Substring(0, indice).Trim();
valor = linea.Substring(indice + 1).Trim();
if (valor.StartsWith("\"") && valor.EndsWith("\""))
{
valor = valor.Substring(1, valor.Length - 2);
}
}
// Console.WriteLine(seccion + "->" + clave + "->" + valor);
if (seccion != "" && clave != "")
{
clave2 = seccion + "-" + clave;
diccionario.Add(clave2, valor);
}
}
}
}
}
}
/// <summary>
/// <para>
/// Es el encargado de buscar entre los datos del diccionario
/// al parametro que necesitamos
/// </para>
/// </summary>
/// <remarks>
/// Esto lo hace por medio de dos valores de tipo string.
/// </remarks>
/// <param name="seccion">El nombre que esta entre corchetes</param>
/// <param name="dato">El valor que esta antes del igual</param>
/// <returns>Devuelve un valor de tipo string</returns>
public string mostrar(string seccion, string dato)
{
string clave = seccion + "-" + dato;
return diccionario[clave];
}
}
}En este caso vamos a ver la primera modificacion que hicimos:
/// <summary>
/// <para>Esta clase se encarga de tomar la informacion de nuestro</para>
/// <para>archivo de configuracion local, se hereda a los otros proyectos</para>
/// </summary>
En este bloque describimos para que sirve esta clase y mas datos, veamos nuestros siguiente bloque de documentacion:
/// <summary>
/// <para>Constructor que recibe el nombre del archivo de configuracion y</para>
/// <para>tambien de forma opcional el parametro que usamos para los </para>
/// <para>comentarios, sino informamos ninguno utiliza el ; como predeterminado</para>
/// </summary>
/// <param name="archivo">Un dato de tipo cadena</param>
/// <param name="comentLimit">Un caracter de tipo cadena</param>Este nos explica que hace este constructor, que recibe el archivo y el caracter de comentario y cual aplica en caso de no informarlo, nuestra siguiente documentacion sera sobre la variable elarchivo:
/// <summary>
/// Variable que por medio de get y set se encarga de abrir el
/// archivo, mirar su interior y en base a las instrucciones
/// que posee almacena los datos en un Diccionario.
/// </summary>Explicamos que usamos un get-set para poder devolver el valor de la variable, y como por medio de set abrimos el archivo de configuracion para guardar todos los datos en un diccionario, nuestra ultima documentacion sera para el metodo mostrar:
/// <summary>
/// <para>
/// Es el encargado de buscar entre los datos del diccionario
/// al parametro que necesitamos
/// </para>
/// </summary>
/// <remarks>
/// Esto lo hace por medio de dos valores de tipo string.
/// </remarks>
/// <param name="seccion">El nombre que esta entre corchetes</param>
/// <param name="dato">El valor que esta antes del igual</param>
/// <returns>Devuelve un valor de tipo string</returns>En esta documentacion volveremos a describir el metodo, tambien los parametros y usaremos a returns para mostrar que devuelve este metodo, con esto terminamos la parte de la documentacion en nuestro codigo, nuestro siguiente paso sera habilitar la documentacion al momento de compilarlo, para ello primero haremos click con el boton derecho sobre el proyecto e iremos a Propiedades, nos aparecera el siguiente cuadro
En este caso elegiremos Compilacion y buscaremos la opcion de Archivo de documentacion XML, una vez tildado nos aparecera un nombre y direccion de carpeta por defecto pero podemos asignarlo a otro lugar y asignar otro nombre, como se ve en la siguiente imagen
Con todo esto configurado podemos proceder a compilarlo y esto nos generara un archivo de tipo XML, con este archivo no solamente documentaremos esto sino que tendremos las siguiente opciones habilitaddas
Esto nos permitira no solamente tener una mejor documentacion sobre nuestros codigos sino que facilitara las descripciones de lo que estamos haciendo aunque tambien sobrecargara el codigo de una forma que personas con poca experiencia puedan quedar apabulladas a simple vista, por lo que te recomiendo que primero te foguees con el lenguaje y cuando tengas bastante experiencia empieces a usar la documentacion.
En resumen, hoy hemos visto que es documentar un codigo, como se hace, los parametros que tenemos disponibles para documentar, hemos tomado un codigo y lo hemos documentado, tambien vimos lo que nos agrega cuando pasamos el mouse sobre alguno de los metodos y/o constructores, espero les haya sido util sigueme en tumblr, Twitter o Facebook para recibir una notificacion cada vez que subo un nuevo post en este blog, nos vemos en el proximo post.
Tengo un Patreon donde podes acceder de manera exclusiva a material para este blog antes de ser publicado, sigue los pasos del link para saber como.
Tambien podes donar
Es para mantenimiento del sitio, gracias!
1.00 $
El blog de Tinchicus 