¿Está bien poner un enlace a sitios de preguntas y respuestas en los comentarios de un programa?

16

En bastante base de código puede ver comentarios que indican cosas como:

 // Workaround for defect 'xxx', (See bug 1434594 on Sun's bugparade)

Así que tengo algunas preguntas, pero todas están relacionadas.

¿Está bien poner un enlace a las preguntas SO en los comentarios de un programa:

 // We're now mapping from the "sorted-on column" to original indices.
 //
 // There's apparently no easy way to do this in Java, so we're
 // re-inventing a wheel.
 //
 // (see why here, in SO question: http://stackoverflow.com/questions/951848)

¿Tú lo haces?

¿Y cuáles son los inconvenientes al hacerlo? (ver mi primer comentario para un terrible inconveniente)

Tristan St.
fuente
99
Comentándome a mí mismo: un inconveniente muy preocupante al hacer eso es que debido a que SO es un Wiki, no hay exactamente ninguna garantía de que la (s) respuesta (s) en la que confía seguirá siendo correcta (o incluso estará allí). Diablos, en algunos casos la pregunta en sí misma podría cerrarse o cambiarse de su significado original. La gran diferencia entre "Ver error 1434594" en el desfile de errores de Sun es que tiene la garantía de que el texto del enlace de errores de Sun no cambiará ( "no" como se define en RFC2119). Esto es enorme: el hecho de que SO sea un wiki me pone nervioso al poner enlaces SO en los comentarios.
Tristan St.
77
Su mejor opción es poner un resumen claro y conciso de la respuesta SO, y luego poner el enlace de referencia debajo de eso. Lo he hecho en varias ocasiones. De esa manera, si SO alguna vez se cae o la respuesta se elimina / edita, la información central que deseaba todavía está en su resumen. Ahora, dependiendo de la complejidad de la respuesta, escribir el resumen podría ser una tarea completamente separada. Si la respuesta SO se vincula a otra cosa, podría valer la pena vincularlas (especialmente si son menos efímeras que las respuestas SO).
FrustratedWithFormsDesigner
55
@Robert S .: no, no es un meta. No se trata de SO: estoy aceptando SO tal como es. Esto es específicamente sobre cómo tratar un recurso similar a SO a partir de un comentario.
Tristan St.
1
¿Estás hablando del código que escribes para tu equipo? Pregúntales.
1
Siempre puede guardar toda la página web como una página web completa, comprimirla y guardarla en su carpeta de documentales.

Respuestas:

7

Lo he hecho, tal vez no específicamente para Stack Overflow, sino para blogs técnicos, foros, Usenet, Grupos de Google o cualquier otro lugar donde el "por qué hice esto" puede no estar completamente claro en el contexto.

No veo por qué usar SO de esta manera sería algo malo, a menos que archiven y eliminen viejas preguntas (lo cual no creo que hagan, pero no estoy seguro), pero incluso si lo hacen, no es peor que cualquier otro sitio.

Si está realmente preocupado por eso, siempre puede tomar capturas de pantalla o descargar estas páginas como texto (o pasar por la molestia de obtener imágenes, hojas de estilo, etc.) y guardarlas en un repositorio de conocimiento de su empresa, adjuntando un identificador único, y poner ese identificador único en sus comentarios para permitirle hacer referencia más tarde, entonces tendría un lugar consistente para este tipo de cosas. Pero eso puede ser excesivo, dependiendo de la complejidad e importancia de su código.

Joe Enos
fuente
5

En general, la mejor manera de crear este enlace es a través del sistema de versiones y / o el sistema de seguimiento de errores. Sin embargo, el requisito para que esto funcione es que puede vincular con precisión su código al rastreador de errores o al lugar en el sistema de versiones donde coloca sus comentarios.


fuente
eso es interesante: entonces, ¿estás sugiriendo que en el caso de una respuesta SO podría obtener el HTML y almacenarlo en mi DVCS (Mercurial pero ese no es el punto)?
Tristan St.
Bueno, normalmente no necesitas todo, solo los bits relevantes, ¿verdad? Y puedes hacer referencia a la fuente.
5

Idealmente, su código no necesita tales comentarios porque está bien estructurado, etc. Pero sí, cuando su situación es menos que ideal, es aceptable incluir comentarios como este. Y los enlaces a stackoverflow.com son tan buenos (¡y a menudo mejores!) Que otros.

Esperemos que sean comentarios temporales, y se le permitirá volver y mejorar el código y sacar estos comentarios .

Todavía no he puesto un enlace StackOverflow.com en mi código. Intento evitar poner enlaces en el código, ya que huele mal, pero cuando llegue el momento no dudaré.

Editar : creo que mi respuesta anterior da la impresión de que la necesidad de comentarios como este es evitable. Por supuesto, a veces es no evitable; es un error en una biblioteca o un diseño de API deficiente sobre el que no tiene control. Comentarios como este, incluidos enlaces, son muy útiles para el próximo desarrollador.

Patrick Karcher
fuente
2
oye, mira eso, desearía que hubiera una forma "más limpia" de tratarlo, pero a menudo no es el caso stackoverflow.com/questions/951848 Quiero decir, errores e inconsistencias / API extraña, comportamiento indocumentado, etc. son parte de nuestra vida de programador :)
Tristan St.
2

Lo veo como escribir un trabajo de investigación. Si uso las ideas de otra persona, entonces debo dar crédito a esas ideas. He usado una respuesta de stackoverflow en mi código antes, y agregué el enlace a los comentarios del método.

Como alguien mencionó, SO es un estilo wiki, por lo que es posible que pueda cambiar, pero en general la idea debería ser la misma.

Todavía debe dar crédito a los demás cuando use sus ideas.

jmq
fuente
1

Si ha necesitado implementar una solución alternativa, y no es obvio por qué la implementación se realizó de una manera particular, entonces debería dejarse un comentario para identificar las razones. Creo que colocar un enlace a una referencia en línea está bien, pero realmente debe haber hecho su comentario conciso, pero lo suficientemente completo como para que el enlace solo proporcione una explicación ampliada si el lector siente la necesidad de verificar su razonamiento.

Si, por otro lado, el código se ha copiado literalmente, entonces un enlace a la fuente original es justo y puede ser necesario dependiendo de la redacción de la licencia bajo la cual se le ha permitido copiar el trabajo del autor original.

S.Robins
fuente