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

Alguien dijo una vez que deberíamos prefijar todos nuestros métodos con los /// <summary>bloques de comentarios (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>bloques de comentarios en su código?

Normalmente uso //comentarios todo el tiempo, son solo los /// <summary>bloques de los que me preguntaba.

Úsalos tanto como sea posible.

Sí, esos son comentarios especiales que se convierten en la documentación del método. El contenido de <summary>las etiquetas de parámetros, etc. que se generan se muestra 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 averiguar qué hace (o simplemente intentar leer la firma del método y esperar lo mejor).

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

Además, úselos junto con Sandcastle y el 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, 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!

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 ) {

    }

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. Por lo 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.

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 funciona algo en los comentarios viola DRY. Si su código no es lo suficientemente descriptivo, tal vez debería regresar y refactorizar.

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 no se sincronizan 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.

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á.

" 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)
{

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

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 al ensamblaje, sin su proyecto, mostrará más detalles en intellisense.

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

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 que 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).

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 que el procedimiento o la función se haya completado bastante antes de ponerlos, solo para evitar tener que cambiar los comentarios, o hacer que estén "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).