Ejemplos de documentación de código

Bueno yo no sé que tan buenas son mis practicas pero aquí te las proveo con
mucho gusto:

1. En todo programa, módulo, etc., utilizo un encabezado ("header") que
contiene información del programa y además contiene información que Visual
SourceSafe estampa en el código automaticamente (como la versión actual,
fecha de guardado, etc.). Este es le encabezado que utilizo yo:

#region Version Header
/// <remarks>
/// $Workfile: MiCodigo.cs $
/// Description: Descripción va aquí.
/// Author: Jose Luis Manners Docs: Jose Luis Manners
/// Created: 06/14/2004 13:18:59pm
/// $Modtime: 06/25/2004 14:23:22pm $
/// $Revision: 3 $
/// Copyright: © 2004 ABC Company
/// </remarks>
#endregion

Lamentablemente aquí en este mensaje no sale propiamente formateado como
saldría en Visual Studio. Y por supuesto, tengo un macro de VS que añade el
encabezado automaticamente.

2. Utilizo una herramienta llamada NDoc para generar archivos de ayuda como
los de MSDN y Visual Studio.

3. Utilizo comentarios XML para las funciones/propiedades. Como por ejemplo:

/// <summary>
/// Establece/devuelve el máximo número de digitos enteros.
/// </summary>
/// <remarks>
/// Esta propiedad no acepta valores menores de 1.
/// </remarks>
/// <seealso cref="MaximoNumeroDeDecimales"/>
[Description("Establece/devuelve el máximo número de digitos enteros.")]
[Category("Behavior")]
public int MaximoNumeroDeEnteros
{
}

Bueno espero que esto te de una idea.
Saludos,

Jose Luis Manners, MCP

"MIguel Angel Ortiz" wrote in message
news:2189801c45ae5$aa3d4810$
Hola grup soy nuevo en .NET y quisiera saber si alguno de
ustedes me podría proveer ejemplos de buenas prácticas de
documentación de código.

Gracias de antemano.

Agregarle el <description> a cada método y propiedad es una buena forma de
empezar :)

Para exportar esa documentación, debes hacer que tu ensamblado genere un XML
y luego lo puedes procesar con NDOC para generar archivos HTML o Windows
Help.

http://ndoc.sf.net

Atte,
Juan C. Olivares
www.juancri.com

"MIguel Angel Ortiz" wrote in message
news:2189801c45ae5$aa3d4810$
Hola grup soy nuevo en .NET y quisiera saber si alguno de
ustedes me podría proveer ejemplos de buenas prácticas de
documentación de código.

Gracias de antemano.

Si es cierto se me olvidó mencionar que tienes que decirle al compilador que
genere XML. Juan gracias por incluír el URL de NDoc. ¡Se me olvidó ponerlo
también!

Saludos,

Jose Luis Manners, MCP

"Juan C. Olivares" wrote in message
news:

Agregarle el <description> a cada método y propiedad es una buena forma de
empezar :)

Para exportar esa documentación, debes hacer que tu ensamblado genere un

XML

y luego lo puedes procesar con NDOC para generar archivos HTML o Windows
Help.

http://ndoc.sf.net

Atte,
Juan C. Olivares
www.juancri.com

"MIguel Angel Ortiz" wrote in

message

news:2189801c45ae5$aa3d4810$
Hola grup soy nuevo en .NET y quisiera saber si alguno de
ustedes me podría proveer ejemplos de buenas prácticas de
documentación de código.

Gracias de antemano.

Me parece muy buena práctica, la acojo enseguida :)



ING. JOSE DAVID GALVIZ MUÑOZ
DCE Tercera Estrella
MCP

"Jose Luis Manners" <jlmanners(-arroba-)acm.org> escribió en el mensaje
news:%

Bueno yo no sé que tan buenas son mis practicas pero aquí te las proveo

con

mucho gusto:

1. En todo programa, módulo, etc., utilizo un encabezado ("header") que
contiene información del programa y además contiene información que Visual
SourceSafe estampa en el código automaticamente (como la versión actual,
fecha de guardado, etc.). Este es le encabezado que utilizo yo:

#region Version Header
/// <remarks>
/// $Workfile: MiCodigo.cs $
/// Description: Descripción va aquí.
/// Author: Jose Luis Manners Docs: Jose Luis Manners
/// Created: 06/14/2004 13:18:59pm
/// $Modtime: 06/25/2004 14:23:22pm $
/// $Revision: 3 $
/// Copyright: © 2004 ABC Company
/// </remarks>
#endregion

Lamentablemente aquí en este mensaje no sale propiamente formateado como
saldría en Visual Studio. Y por supuesto, tengo un macro de VS que añade

el

encabezado automaticamente.

2. Utilizo una herramienta llamada NDoc para generar archivos de ayuda

como

los de MSDN y Visual Studio.

3. Utilizo comentarios XML para las funciones/propiedades. Como por

ejemplo:

/// <summary>
/// Establece/devuelve el máximo número de digitos enteros.
/// </summary>
/// <remarks>
/// Esta propiedad no acepta valores menores de 1.
/// </remarks>
/// <seealso cref="MaximoNumeroDeDecimales"/>
[Description("Establece/devuelve el máximo número de digitos enteros.")]
[Category("Behavior")]
public int MaximoNumeroDeEnteros
{
}

Bueno espero que esto te de una idea.
Saludos,

Jose Luis Manners, MCP

"MIguel Angel Ortiz" wrote in

message

news:2189801c45ae5$aa3d4810$
Hola grup soy nuevo en .NET y quisiera saber si alguno de
ustedes me podría proveer ejemplos de buenas prácticas de
documentación de código.

Gracias de antemano.

Si estas en VB.Net, puedes usar VB Commenter
http://www.gotdotnet.com/community/...ds.aspx?id2b5449-f702-46e2-87fa-86bdf39a17dd

Saludos,
Eugenio Serrano
NDSoft Consultoria y Desarrollo
MS MVP ASP.Net
Instructor 3 estrella (DCE)
Voluntario Ineta Latam

"MIguel Angel Ortiz" escribió en el
mensaje news:2189801c45ae5$aa3d4810$
Hola grup soy nuevo en .NET y quisiera saber si alguno de
ustedes me podría proveer ejemplos de buenas prácticas de
documentación de código.

Gracias de antemano.