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

15

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

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

Tengo algunas preguntas, pero todas están relacionadas.

¿Está bien poner el enlace a las preguntas de 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)

¿Lo haces?

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

    
pregunta Tristan St. 17.05.2010 - 18:42

5 respuestas

7

Lo he hecho, tal vez no específicamente para el Desbordamiento de Pila, pero 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 las preguntas antiguas (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 las imágenes, hojas de estilo, etc.) y guardarlas en un repositorio de conocimientos en su empresa. , adjuntándole un identificador único y colocando ese identificador único en sus comentarios para permitirle hacer referencia más adelante, entonces tendría un lugar coherente para este tipo de cosas. Pero eso puede ser excesivo, dependiendo de la complejidad e importancia de su código.

    
respondido por el Joe Enos 17.05.2010 - 18:47
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 coloque sus comentarios.

    
respondido por el Loki 17.05.2010 - 18:46
5

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

Esperamos que sean comentarios temporales, y se le permitirá regresar y mejorar el código y eliminar estos comentarios .

Todavía no he puesto un enlace de StackOverflow.com en mi código. Intento evitar poner enlaces en el código, ya que huele mal, pero cuando llegue el momento no lo 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 mal diseño de API sobre el que no tienes control. Los comentarios como este, incluidos los enlaces, son muy útiles para el próximo desarrollador.

    
respondido por el Patrick Karcher 17.05.2010 - 18:45
2

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

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

Aún debes dar crédito a otros cuando usas sus ideas.

    
respondido por el jmq 03.02.2012 - 10:03
1

Si ha necesitado implementar una solución alternativa, y no es obvio why la implementación se realizó de una manera particular, entonces se debe dejar un comentario para identificar las razones por las cuales 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 más amplia en caso de que el lector sienta la necesidad de volver a 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.

    
respondido por el S.Robins 03.02.2012 - 11:16

Lea otras preguntas en las etiquetas