it-swarm-es.com

¿Por qué son /// los bloques de comentarios importantes?

Alguien dijo una vez que deberíamos anteponer todos nuestros métodos con el /// <summary> comenta los bloques (C #) pero no explicó por qué.

Comencé a usarlos y descubrí que me molestaban bastante, así que dejé de usarlos, excepto para las bibliotecas y los métodos estáticos. Son voluminosos y siempre me olvido de actualizarlos.

¿Hay alguna buena razón para usar /// <summary> comenta bloques en tu código?

Normalmente uso // comenta todo el tiempo, es solo el /// <summary> bloques por los que me preguntaba.

49
Rachel

Úselos tanto como sea posible

Sí, esos son comentarios especiales que se convierten en la documentación del método. Los contenidos de <summary>, las etiquetas de parámetros, etc. que se generan aparecen en intellisense cuando usted u otra persona se está preparando para llamar a su método. Esencialmente, pueden ver toda la documentación de su método o clase sin tener que ir al archivo en sí para descubrir qué hace (o simplemente intentar leer la firma del método y esperar lo mejor).

91
Ryan Hayes

Sí, úsalas absolutamente para cualquier cosa que quieras conservar o que puedas compartir.

Además, úselos junto con Sandcastle y Sandcastle Help File Builder , que toma la salida XML y la convierte en una hermosa documentación de estilo MSDN.

El último lugar donde trabajé reconstruimos la documentación todas las noches y la alojamos como una página de inicio interna. Las iniciales de la compañía eran MF, por lo que era MFDN;)

Normalmente, aunque solo produzco un archivo .chm, que se comparte fácilmente.

¡Te sorprenderá lo adicto que eres a documentar todo una vez que comiences a verlo en formato MSDN!

17
Tom Morgan

Si su estándar de codificación exige que utilice dichos comentarios (y un estándar de codificación para una API o un marco puede exigir eso), entonces no tiene otra opción, debe utilizar dichos comentarios.

De lo contrario, considere seriamente no usar tales comentarios. Puede evitarlos en la mayoría de los casos cambiando su código de esta manera:

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool SecurityCheck( User user ) {

    }

a

    /// <summary>
    /// Checks if a user is authorized to access the resource
    /// </summary>
    public bool IsAuthorizedToAccessResource( User user ) {

    }

a

    public bool IsAuthorizedToAccessResource( User user ) {

    }
12
azheglov

Su clase, método y nombre de propiedad deben ser evidentes, por lo que si los necesita, probablemente sea un olor.

Sin embargo, recomendaría usarlos en cualquier clase pública, métodos y propiedades en una API, biblioteca, etc. Al menos, generarán los documentos para ayudar a cualquier desarrollador que lo use y evitarán que tenga para escribirlos.

Pero de todos modos lo corta, lo mantiene o lo elimina.

4
John MacIntyre

Si descubre que tiene que seguir retrocediendo y editando sus comentarios para que se correspondan con el nuevo código, es posible que los esté haciendo mal en primer lugar. El elemento de resumen debe contener exactamente eso, un resumen, el qué y el por qué de lo que está resumiendo.

Describir cómo algo funciona en los comentarios viola DRY. Si su código no es lo suficientemente descriptivo, tal vez debería regresar y refactorizar.

2
Nobody

Sí, los he creado. [al construir nuevos sistemas desde cero]

No, nunca me he beneficiado de ellos. [cuando se trabaja en sistemas existentes que necesitaban mantenimiento]

Descubrí que los comentarios de "Resumen" eventualmente tienden a estar fuera de sincronización con el código. Y una vez que noto algunos comentarios que se comportan mal, tiendo a perder la fe en todos los comentarios sobre ese proyecto; nunca estás seguro de en qué confiar.

1
Preets

Olvidar hacer algo no lo convierte en una mala idea. Olvidar actualizar cualquier documentación es. Los he encontrado muy útiles en mi programación y las personas que heredan mi código están agradecidos de tenerlos.

Es una de las formas más visibles de documentar su código.

Es difícil tener que encontrar el código fuente para leer la documentación en línea o desenterrar un documento que revise lo que hace el código. Si puede hacer aparecer algo útil a través de la inteligencia, la gente lo amará.

1
Abe Miessler

"Tiene que ser usado mucho, como yo;)"

Solía ​​jugar con comentarios (///). Para una clase simplemente puedes hacer un comentario como este

namespace test
{
    /// <summary>
    /// Summary description for Calendar.
    /// </summary>
    public partial class DatePicker : System.Web.UI.Page
    {

Pero, para un método, puede agregar más con la descripción de parámetros y tipos de retorno.

/// <summary>
/// Assign selected cases to the participating users based on the filters and configurations
/// </summary>
/// <param name="noOfParticipants">No. of participants to the Table</param>
/// <param name="value">Value of the participant</param>
/// <returns>No Of Cases Assigned on successfull completion</returns>
public long AssignCasesToParticipatingUsers(int noOfParticipants,string value)
{

Puedes usar un atajo para crear este comentario (///+Tab).

1
Sreekumar P

Uso el equivalente en VB (ya que no me dejan usar C #, aparentemente es demasiado difícil ... sin comentarios). Me parece muy conveniente. La mayoría de las veces espero hasta el procedimiento o la función está prácticamente completado antes de ponerlos, aunque solo sea para evitar tener que cambiar los comentarios, o hacerlos "fuera de sincronización".

No necesariamente escribo una novela, solo los conceptos básicos, la descripción del parámetro y algunos comentarios (generalmente cuando hay algo "fuera de lo común" que está sucediendo allí, una solución u otra basura que preferiría no tener allí pero que tengo no hay opción "por ahora".) (Sí, lo sé, que "por ahora" puede durar años).

Estoy muy irritado por el código no comentado. Un consultor escribió la versión inicial de uno de nuestros componentes y no comentó nada y su elección de nombres deja que desear aquí y allá. Se fue hace más de un año y todavía estamos resolviendo sus cosas (además de trabajar en nuestras propias cosas).

0
MetalMikester

usándolos excepto para bibliotecas

Ese es el momento en que son útiles. Con la generación de documentación XML activada y una referencia a la Asamblea, sin su proyecto, mostrará más detalles en intellisense.

Pero para los aspectos internos del proyecto actual, simplemente se interponen en el camino.

0
Richard

Los uso, pero como han dicho otras personas no universalmente. Para métodos pequeños, pueden ser fácilmente más grandes que el código que están explicando. Son más útiles para generar documentación que se puede dar a las personas nuevas en el sistema para que tengan algo a lo que referirse mientras lo aprenden. A pesar de que, como programadores, generalmente podemos descubrir qué es un código, ya que es bueno tener los comentarios para guiarnos y actuar como una muleta. Si tiene para escribirse en algún lugar, entonces en el código es el lugar donde es más probable que se mantenga actualizado (más probable que algún documento de Word flotando).

0
Todd Williamson