¿Debo agregar notas de MSDN o enlaces de desbordamiento de pila al código fuente? [duplicar]

7

Estoy creando un host powershell / C # y quiero agregar el siguiente comentario

// This method cannot be called multiple times on a given pipeline. The state of the 
// pipeline must be NotStarted when Invoke is called. When this method is called, it
// changes the state of the pipeline to Running. 
// see http://msdn.microsoft.com/en-us/library/windows/desktop/ms569128(v=vs.85).aspx
if (pipeline.PipelineStateInfo.State == PipelineState.NotStarted)
{
    Collection<PSObject> results = pipeline.Invoke();
}

¿Es este un comentario apropiado? ¿Qué mejorarías al respecto?

    
pregunta random65537 11.02.2012 - 16:33

6 respuestas

12

Un enlace externo está bien, quizás con una breve sinopsis de por qué dicho enlace es interesante. Si es posible, mantenga el comentario completo en una sola línea.

Si le preocupa que el enlace no sea válido en el futuro, haga una copia local de la página web (Internet Explorer permite guardar una página web completa, incluidas las imágenes en un solo archivo) y coloque el archivo en su carpeta de documentación y enlace. a eso.

    
respondido por el user1249 11.02.2012 - 16:36
7

El punto de un comentario es explicar por qué algo está codificado de la forma en que está. Su comentario es una buena explicación de por qué tiene esa comprobación adicional del estado de la canalización allí.

Sin embargo, creo que el enlace es redundante, ya que simplemente apunta a la versión actual de la documentación para el método Invoke . A menos que su editor tenga soporte para hacer clic en dichos enlaces http, creo que es más rápido simplemente presionar F1 en el método Invoke para mostrar su documentación. Los enlaces también pueden cambiar y utilizar el sistema de ayuda para obtener la documentación de un método parece la forma más natural de obtener la información más actualizada sobre un método.

Las cosas serían diferentes, sin embargo, si ese fuera un enlace a una pregunta de desbordamiento de pila o alguna otra fuente que resuelva un problema particular que tenía con un fragmento de código, por ejemplo. Información más allá de lo que se proporciona en la documentación oficial. Especialmente si le tomó un tiempo encontrarlo en línea, podría valer la pena mantener el enlace en su código. Pero como no se garantiza que las publicaciones de desbordamiento de pila estén disponibles para siempre, hacer una copia local de la publicación podría ser más sensato si la información es fundamental para comprender un fragmento de código.

    
respondido por el PersonalNexus 11.02.2012 - 16:48
5

Siempre es bueno encontrar un comentario corto donde sea necesario. Apoyo a mis compañeros de equipo cuando colocan un hipervínculo a una buena fuente de conocimiento en lugar de escribir una larga historia sobre lo que está sucediendo aquí. Este enfoque limpia su código y mantiene su comentario actualizado.

    
respondido por el Igor Soloydenko 11.02.2012 - 17:06
1

Su comentario no es necesario ya que el código es lo suficientemente claro como para explicar que no hará nada si el estado no se inicia. Si se llama varias veces, entonces no tiene ningún efecto. Tal vez, debería considerar el nombre del método para describir claramente la intención de su método.

En el caso separado de poner referencias en su código, entonces sí, agréguelas si realmente agregan valor.

    
respondido por el PenFold 11.02.2012 - 16:52
1

Sí.

Agregar enlaces a tu código es una buena práctica, y lo que lo hace mejor es que estás explicando tu razonamiento para hacerlo.

Una cosa que mejoraría con respecto al comentario es dejar algo de espacio entre el enlace y el comentario para una mejor lectura.

Otra práctica (alternativa) sería, además de agregar el enlace, hacer de tu comentario un extracto del artículo.

    
respondido por el Dynamic 11.02.2012 - 20:10
1

Si el programa no es trivial, entonces su código debe ser independiente y pasar las pruebas del tiempo. Si el código fuente se pierde, entonces no se cambiará ni se leerá, pero, de lo contrario, el código puede permanecer durante mucho tiempo. Algunos de los usuarios de SO más antiguos tendrán historias sobre el código que tiene varias décadas de antigüedad aún en ejecución.

He trabajado en sistemas que todavía estaban en desarrollo activo después de décadas. Los enlaces a los sitios web estarían rotos para cuando un nuevo programador quisiera leerlos.

Como no se garantiza la existencia de MSDN o SO, todo lo que hace un enlace es irritar.

Sir Tim Berners Lee escribió una súplica muy apasionada de que las URL sean constantes, por lo que los enlaces tendrían valor en el futuro. Hasta ahora, no tan exitoso. Tal vez hubiéramos estado mejor si hubiera patentado la web y nos obligó a hacerlo a su manera como parte de los términos de la licencia.

    
respondido por el Tim Williscroft 13.02.2012 - 01:10

Lea otras preguntas en las etiquetas