Políticas de comentariado en APG

Para la documentación en APG se sugieren las siguientes políticas en cuanto al uso del XML de documentación del código.

NOTA: Es importante saber que al escribir triple slashes (///) sobre una clase, método o propiedad Visual Studio nos ayuda colocando las etiquetas mínimas requeridas según como esté compuesta la clase, método o propiedad.

Definición de encabezado del documento

La definición de encabezado del documento se realiza en la parte superior del documento anterior a cualquier parte del código y define los derechos del código, el autor que la creo y la fecha de creación:

//---------------------------------------------------------------------------
// <copyright file="Extensiones.cs" company="APG Consulting">
// Copyright (c) 2017 Todos los derechos reservados.
// </copyright>
// <created><author>apedrozo</author><date>22/09/2017</date></created>
// <updated><author>[autor]</author><date>[dd/MM/yyyy]</date></updated>
//---------------------------------------------------------------------------
namespace APG.Utiles
{
    #region using

    using System; 

    #endregion

    /// <summary>
    /// Clase que define métodos extras para diferentes tipos de datos.
    /// </summary>
    public static class Extensiones
    {
        /* AQUÍ VA EL CÓDIGO DE LA CLASE */
    }
}

NOTA: Para adicionar directamente este template en tu Visual Studio descarga el .snippet y sigue los pasos de la sección Agregar Code Snippet. El shorcut para este snippet es apgh.

Template general para las clases

Para las clases en general se define el siguiente template:

/// <summary>
/// **Comentario general de la clase**.
/// </summary>
/// <remarks>
/// **Descripción detallada de la clase**
/// </remarks>
public class NombreClase
{
}

NOTA: Para adicionar directamente este template en tu Visual Studio descarga el .snippet y sigue los pasos de la sección Agregar Code Snippet. El shorcut para este snippet es apgc.

Template general para los métodos

Para los métodos en general se define el siguiente template:

/// <summary>
/// **Comentario breve sobre la funcionalidad**.
/// </summary>
/// <param name="**Nombre parametro**">**Descripción del párametro(OPCIONAL)**.</param>
/// <remarks>
/// **Descripción detallada de la funcionalidad**.
/// Este método llama el/los siguiente(s) método(s):
/// <list type="number">  
///     <item><see cref="**Clase.Método(params)(OPCIONAL)**"/></item>
///     <item><see cref="**Clase.Método(params)(OPCIONAL)**"/></item>
/// </list>
/// </remarks>
/// <returns>**Comentario del return(OPCIONAL)**.</returns>
public **Tipo** NombreMetodo(**Tipo** **Nombre parametro**)
{
}

NOTA: Para adicionar directamente este template en tu Visual Studio descarga el .snippet y sigue los pasos de la sección Agregar Code Snippet. El shorcut para este snippet es apgm.

Template para métodos con polimorfismo

/// <summary>
/// **Comentario breve sobre la funcionalidad**.
/// </summary>
/// <param name="**Nombre parametro**">**Descripción del párametro(OPCIONAL)**.</param>
/// <remarks>
/// **Descripción detallada**.
/// Este método llama el/los siguiente(s) método(s):
/// <see cref="**Clase.Método(params)(OPCIONAL)**"/>
/// <list type="bullet">
///     <item>
///         COL: **Comentario**
///        <list type="number">
///        <item><see cref="**Clase.Método(params)(OPCIONAL)**"/></item>
///        </list>
///     </item>
///     <item>
///         ECU: **Comentario**
///        <list type="number">
///            <item><see cref="**Clase.Método(params)(OPCIONAL)**"/></item>
///        </list>
///    </item>
///     <item>
///         BOL: **Comentario**
///        <list type="number">
///            <item><see cref="**Clase.Método(params)(OPCIONAL)**"/></item>
///        </list>
///     </item>
///     <item>
///         ARG: **Comentario**
///        <list type="number">
///        <item><see cref="**Clase.Método(params)(OPCIONAL)**"/></item>
///        </list>
///     </item>
///     <item>
///         CRI: **Comentario**
///        <list type="number">
///            <item><see cref="**Clase.Método(params)(OPCIONAL)**"/></item>
///        </list>
///     </item>
///     <item>
///         PER: **Comentario**
///        <list type="number">
///            <item><see cref="**Clase.Método(params)(OPCIONAL)**"/></item>
///        </list>
///     </item>
/// </list>
/// </remarks>
/// <returns>**Comentario del return(OPCIONAL)**.</returns>
public **Tipo** NombreMetodo(**Tipo** **Nombre parametro**)
{
}

NOTA: Para adicionar directamente este template en tu Visual Studio descarga el .snippet y sigue los pasos de la sección Agregar Code Snippet. El shorcut para este snippet es apgmp.

Para cada país se usará la codificiación alpha-3 de la ISO 3166-1:

ARG: Argentina
BOL: Bolivia
COL: Colombia
CRI: Costa Rica
ECU: Ecuador
PER: Perú