Escritura de documentación para proyectos C#: de la A a la Z

Escritura de documentación para proyectos C#: de la A a la Z

La documentación de calidad es la clave del éxito y el mantenimiento de un proyecto C#. Ayuda a los desarrolladores a comprender rápidamente el código, facilita la incorporación de nuevos miembros al equipo y reduce la cantidad de errores. En este artículo, analizaremos el proceso completo de creación de documentación para un proyecto C# (.NET): desde los fundamentos de los comentarios XML hasta la generación automática de sitios web atractivos.

1. Fundamentos de los comentarios XML en C#

La forma estándar de documentar el código en C# son los comentarios XML. Se escriben antes de la declaración de una clase, método, propiedad u otro elemento y comienzan con tres barras ///. El compilador de C# reconoce estos comentarios y puede generar un archivo XML de documentación.

Estas son las etiquetas básicas que usará con más frecuencia:

\n
• <summary> — descripción breve del elemento.
\n
• <param name="nombre"> — descripción del parámetro del método.
\n
• <returns> — descripción del valor devuelto.
\n
• <exception cref="Tipo"> — descripción de la excepción que puede lanzar el método.
\n
• <example> — ejemplo de uso.
\n
• <remarks> — notas adicionales.
\n

Ejemplo de un comentario XML correcto para un método:

/// <summary>\n/// Calcula el factorial de un número entero no negativo.\n/// </summary>\n/// <param name="n">Número entero no negativo.</param>\n/// <returns>Factorial del número n.</returns>\n/// <exception cref="System.ArgumentException">Se lanza si n es menor que 0.</exception>\n/// <example>\n/// <code>\n/// int result = Factorial(5);\n/// // result es igual a 120\n/// </code>\n/// </example>\npublic static int Factorial(int n)\n{\n    if (n < 0)\n        throw new ArgumentException("n no puede ser negativo", nameof(n));\n\n    int result = 1;\n    for (int i = 1; i <= n; i++)\n    {\n        result *= i;\n    }\n    return result;\n}

2. Documentación de clases y propiedades

No olvide documentar no solo los métodos, sino también las clases mismas, así como sus propiedades y campos. Esto es especialmente importante para las API públicas que serán utilizadas por otros desarrolladores.

Para las propiedades, use las etiquetas <summary> y <value> (para describir el valor almacenado):

/// <summary>\n/// Representa un usuario del sistema.\n/// </summary>\npublic class User\n{\n    /// <summary>\n    /// Identificador único del usuario.\n    /// </value>\n    public int Id { get; set; }\n\n    /// <summary>\n    /// Nombre completo del usuario.\n    /// </summary>\n    /// <value>Cadena que contiene el nombre y apellido.</value>\n    public string FullName { get; set; }\n\n    /// <summary>\n    /// Crea un nuevo usuario.\n    /// </summary>\n    /// <param name="id">Identificador.</param>\n    /// <param name="fullName">Nombre completo.</param>\n    public User(int id, string fullName)\n    {\n        Id = id;\n        FullName = fullName ?? throw new ArgumentNullException(nameof(fullName));\n    }\n}

3. Generación del archivo XML y compilación de la documentación

Para obtener un archivo XML a partir de sus comentarios, debe configurar el proyecto. En Visual Studio o a través del archivo .csproj, agregue:

<PropertyGroup>\n  <GenerateDocumentationFile>true</GenerateDocumentationFile>\n  <DocumentationFile>bin\\$(Configuration)\\$(TargetFramework)\\$(AssemblyName).xml</DocumentationFile>\n  <NoWarn>$(NoWarn);1591</NoWarn> <!-- Desactiva la advertencia sobre comentarios faltantes, si es necesario -->\n</PropertyGroup>

Después de compilar el proyecto, obtendrá un archivo XML que se puede utilizar para crear un sitio web de documentación atractivo utilizando herramientas como DocFX o Sandcastle.