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

  

Úsalos lo más 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 muestran inteligentemente cuando usted o alguien más se está preparando para llamar a su método. Básicamente, pueden ver toda la documentación de su método o clase sin tener que ir al archivo para averiguar qué hace (o simplemente leer la firma del método y esperar lo mejor).

Sí, utilícelas absolutamente para cualquier cosa que desee conservar o que pueda compartir.

También, utilícelos junto con Sandcastle y Sandcastle Help File Builder , que toma la salida XML y la convierte en una hermosa documentación al estilo de MSDN.

En 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 empresa fueron MF, por lo que era MFDN;)

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

¡Se sorprendería de lo adicto que llega a documentar todo una vez que comienza a verlo en formato MSDN!

Si su estándar de codificación exige que use dichos comentarios (y un estándar de codificación para una API o un marco puede exigirlo), entonces no tiene otra opción, tiene que usar dichos comentarios.

De lo contrario, considera 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 ) {

    }

Tu clase, método y & la denominación de las propiedades debe ser evidente, por lo que si las necesita, probablemente sea un olor.

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

Pero de todos modos, córtalos, mantenlos o elimínalos.

Si encuentra que tiene que volver atrás y editar 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ás resumiendo.

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

Sí, los he creado. [cuando se construyen nuevos sistemas desde cero]

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

Encontré que los comentarios "Resumen" eventualmente tienden a desincronizarse con el código. Y una vez que me doy cuenta de algunos comentarios que se comportan mal, tiendo a perder la fe en todos los comentarios sobre ese proyecto, nunca estás seguro de cuáles confiar.

Olvidar hacer algo no hace que sea una mala idea. Olvidarse de actualizar cualquier documentación es. Los he encontrado muy útiles en mi programación y la gente que hereda mi código está agradecida de tenerlos.

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

Es un dolor tener que encontrar el código fuente para leer la documentación en línea o desenterrar un documento que explique qué código hace. Si puedes tener algo útil a través de la inteligencia, entonces la gente te amará.

  

" Debe usarse mucho, como yo;) "

Solía jugar con comentarios (///). Para una clase, simplemente puede 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 una descripción de los parámetros y tipos de devolución.

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

  

usándolos a excepción de las 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, se mostrarán más detalles en inteligencia.

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

Los uso, pero como otras personas no han dicho universalmente. Para los métodos pequeños, pueden ser fácilmente más grandes que el código que están explicando. Son muy útiles para generar documentación que se puede entregar a 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, porque es bueno tener los comentarios que nos guían y actúan como una muleta. Si tiene estar escrito 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 un documento de Word flotando alrededor).

Utilizo el equivalente en VB (ya que no me dejan usar C #, aparentemente es demasiado difícil ... no hay comentarios). Los encuentro muy convenientes. La mayoría de las veces, espero hasta que el procedimiento o la función se complete bastante antes de ponerlos, aunque sea solo para evitar tener que cambiar los comentarios, o que estén "desincronizados".

No necesariamente escribo una novela, solo lo básico, la descripción del parámetro y algunas observaciones (por lo general, cuando algo "fuera de lo común" está sucediendo allí - solución alternativa u otra mierda que preferiría no tener en allí, pero no tengo opción "por ahora".) (Sí, lo sé, que "por ahora" puede durar años).

Estoy muy irritado por el código sin comentarios. Un consultor escribió la versión inicial de uno de nuestros componentes y no comentó nada, y su elección de nombres deja que desearse 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).