Est-il correct de mettre un lien vers des sites de questions / réponses dans les commentaires d'un programme?

16

Dans une certaine base de code, vous pouvez voir des commentaires indiquant des choses comme:

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

J'ai donc quelques questions, mais elles sont toutes liées.

Est-il correct de mettre un lien vers les questions SO dans les commentaires d'un programme:

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

Est-ce que vous le faites?

Et quels sont les inconvénients à le faire? (voir mon premier commentaire pour un terrible inconvénient)

comments Tristan St.
la source
9
en me disant: un inconvénient très inquiétant lorsque vous faites cela est que, du fait que SO est un wiki, il n'y a exactement aucune garantie que la ou les réponses sur lesquelles vous vous appuyerez seront toujours correctes (ou même seront toujours là). Heck, dans certains cas, la question elle-même pourrait être fermée ou modifiée par rapport à sa signification d'origine. La grande différence entre "Voir le bogue 1434594" sur la parade de bogues de Sun est que vous êtes assuré que le texte du lien de bogue de Sun ne changera pas ( "ne doit pas" comme défini par RFC2119). C'est énorme: le fait que SO soit un wiki me rend nerveux de mettre des liens SO dans les commentaires.
rue Tristan
7
Votre meilleur pari est de mettre un résumé clair et concis de la réponse SO, puis de mettre le lien de référence en dessous. Je l'ai fait à plusieurs reprises. De cette façon, si SO tombe en panne ou si la réponse est supprimée / modifiée, les informations de base que vous recherchez sont toujours dans votre résumé. Maintenant, selon la complexité de la réponse, la rédaction du résumé pourrait être une corvée à part entière. Si la réponse SO renvoie à quelque chose d'autre, cela peut valoir la peine de se lier à ces réponses (surtout si elles sont moins éphémères que les réponses SO).
FrustratedWithFormsDesigner
5
@Robert S .: non, ce n'est pas une méta. Il ne s'agit pas de SO: j'accepte SO tel quel. Il s'agit spécifiquement de la façon de traiter une ressource de type SO à partir d'un commentaire.
Tristan St.
1
Parlez-vous de code que vous écrivez pour votre équipe? Leur demander.
1
Vous pouvez toujours enregistrer la page Web entière en tant que page Web complète, la compresser et la placer dans votre dossier documentaire.

Réponses:

7

Je l'ai fait, peut-être pas spécifiquement pour Stack Overflow, mais pour les blogs techniques, les forums, Usenet, les groupes Google ou tout autre endroit où le "pourquoi ai-je fait cela" peut ne pas être complètement clair du contexte.

Je ne vois pas pourquoi utiliser SO comme ça serait une mauvaise chose, à moins qu'ils archivent et purgent les anciennes questions (ce que je ne pense pas, mais je ne suis pas sûr) - mais même s'ils le font, ce n'est pas pire que tout autre site.

Si cela vous inquiète vraiment, vous pouvez toujours prendre des captures d'écran ou télécharger ces pages sous forme de texte (ou passer par la difficulté d'obtenir les images, les feuilles de style, etc.) et les enregistrer dans un référentiel de connaissances de votre entreprise, en joignant un identifiant unique et en mettant cet identifiant unique dans vos commentaires pour vous permettre de faire référence plus tard - alors vous auriez une place cohérente pour ce type de chose. Mais cela peut être exagéré, selon la complexité et l'importance de votre code.

Joe Enos
la source
5

Généralement, la meilleure façon de créer ce lien est via le système de version et / ou le système de suivi des bogues. La condition pour que cela fonctionne est que vous pouvez lier avec précision votre code au suivi des bogues ou à l'emplacement dans le système de versionning où vous placez vos commentaires.


la source
c'est intéressant: vous suggérez en fait que dans le cas d'une réponse SO je pourrais récupérer le HTML et le stocker dans mon DVCS (Mercurial mais ce n'est pas le but)?
Tristan St.
Eh bien, normalement, vous n'avez pas besoin de tout, juste des bits pertinents, non? Et vous pouvez référencer la source.
5

Idéalement, votre code n'a pas besoin de tels commentaires car il est bien structuré, etc. Mais oui, lorsque votre situation n'est pas idéale, il est acceptable de mettre des commentaires comme celui-ci. Et les liens vers stackoverflow.com sont aussi bons (et souvent meilleurs!) Que les autres.

J'espère que ce sont des commentaires temporaires, et vous serez autorisé à revenir et à améliorer le code et à retirer ces commentaires .

Je n'ai pas encore mis de lien StackOverflow.com dans mon code. J'essaie d'éviter de mettre des liens dans le code, car c'est une mauvaise odeur, mais le moment venu, je n'hésiterai pas.

Edit : Je pense que ma réponse ci-dessus donne l'impression que le besoin de commentaires comme celui-ci est évitable. Bien sûr, parfois, ce n'est pas évitable; c'est un bug dans une bibliothèque ou une mauvaise conception d'API sur laquelle vous n'avez aucun contrôle. Des commentaires comme celui-ci, y compris des liens, sont très utiles pour le prochain développeur.

Patrick Karcher
la source
2
Hé, regardez celui-là, j'aimerais qu'il y ait une façon "plus propre" de le gérer, mais très souvent ce n'est pas le cas stackoverflow.com/questions/951848 je veux dire, bugs et incohérences / API bizarre, comportement non documenté, etc. font partie de la vie de nos programmeurs :)
Tristan St.
2

Je le vois comme écrire un document de recherche. Si j'utilise les idées de quelqu'un d'autre, alors je dois les reconnaître. J'ai déjà utilisé une réponse de stackoverflow dans mon code, et j'ai ajouté le lien vers les commentaires de méthode.

Comme quelqu'un l'a mentionné, SO est un style wiki, il est donc possible que cela change, mais généralement l'idée devrait être la même.

Vous devriez quand même donner du crédit aux autres lorsque vous utilisez leurs idées.

jmq
la source
1

Si vous avez dû implémenter une solution de contournement, et que la raison pour laquelle l'implémentation a été effectuée d'une manière particulière n'est pas évidente , alors un commentaire devrait vraiment être laissé pour identifier les raisons. Je pense que placer un lien vers une référence en ligne est bien, mais vous devez vraiment avoir fait votre commentaire succinct, mais suffisamment complet pour que le lien ne fournisse une explication détaillée que si le lecteur ressent le besoin de revérifier votre raisonnement.

Si d'un autre côté le code a été copié textuellement, alors un lien vers la source originale est juste et peut être requis en fonction du libellé de la licence sous laquelle vous avez été autorisé à copier le travail de l'auteur original.

S.Robins
la source