Ist es in Ordnung, in den Kommentaren eines Programms einen Link zu Q & A-Sites zu setzen?

16

In einigen Codebasen können Sie Kommentare sehen, in denen Dinge wie:

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

Ich habe ein paar Fragen, aber sie hängen alle zusammen.

Ist es in Ordnung, in den Kommentaren eines Programms Links zu SO-Fragen zu setzen:

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

Machst du es?

Und was sind die Nachteile dabei? (siehe meinen ersten Kommentar für einen schrecklichen Nachteil)

comments Tristan St.
quelle
9
Bemerkung zu mir selbst: Ein sehr besorgniserregender Nachteil dabei ist, dass es aufgrund der Tatsache, dass SO ein Wiki ist, keine Garantie dafür gibt, dass die Antworten, auf die Sie sich verlassen, immer noch richtig sind (oder sogar immer noch da sind). Heck, in einigen Fällen könnte die Frage selbst geschlossen oder von seiner ursprünglichen Bedeutung geändert werden. Der große Unterschied zwischen "See bug 1434594" in Suns Bug-Parade besteht darin, dass garantiert wird, dass sich der Text aus Suns Bug-Link nicht ( "soll nicht" wie in RFC2119 definiert) ändert. Das ist riesig: Die Tatsache, dass SO ein Wiki ist, macht mich nervös, SO-Links in Kommentare zu setzen.
Tristan St.
7
Am besten ist es, eine klare und prägnante Zusammenfassung der SO-Antwort zu erstellen und dann den Referenzlink darunter zu platzieren. Ich habe das schon mehrmals gemacht. Auf diese Weise sind die Kerninformationen, die Sie benötigen, immer noch in Ihrer Zusammenfassung enthalten, falls SO jemals untergeht oder die Antwort entfernt / bearbeitet wird. Je nach Komplexität der Antwort kann das Schreiben der Zusammenfassung eine separate Aufgabe sein. Wenn die SO-Antwort auf etwas anderes verweist, lohnt es sich möglicherweise, auf diese zu verweisen (insbesondere, wenn sie weniger kurzlebig sind als SO-Antworten).
FrustratedWithFormsDesigner
5
@ Robert S .: Nein, es ist kein Meta. Es geht nicht um SO: Ich akzeptiere SO so wie es ist. Hier geht es speziell darum, wie mit einer SO-ähnlichen Ressource aus einem Kommentar umgegangen wird.
Tristan St.
1
Sprechen Sie von Code, den Sie für Ihr Team schreiben? Frag sie.
1
Sie können die gesamte Webseite jederzeit als vollständige Webseite speichern, komprimieren und in Ihren Dokumentationsordner legen.

Antworten:

7

Ich habe es getan, vielleicht nicht speziell für Stack Overflow, sondern für technische Blogs, Foren, Usenet, Google Groups oder andere Orte, an denen das "Warum habe ich das getan" möglicherweise nicht vollständig aus dem Kontext hervorgeht.

Ich verstehe nicht, warum es eine schlechte Sache ist, SO so zu verwenden, es sei denn, sie archivieren und löschen alte Fragen (von denen ich glaube, dass sie es nicht tun, aber ich bin nicht sicher) - aber selbst wenn sie es tun, ist es nein schlimmer als jede andere Website.

Wenn Sie sich darüber wirklich Sorgen machen, können Sie jederzeit Screenshots erstellen oder diese Seiten als Text herunterladen (oder sich die Mühe machen, Bilder, Stylesheets usw. abzurufen) und sie in einem Wissensspeicher in Ihrem Unternehmen zu speichern, indem Sie eine anhängen eine eindeutige Kennung, die Sie später in Ihre Kommentare aufnehmen können, um später darauf zu verweisen - dann hätten Sie einen einheitlichen Platz für diese Art von Dingen. Aber das kann übertrieben sein, abhängig von der Komplexität und Wichtigkeit Ihres Codes.

Joe Enos
quelle
5

Im Allgemeinen lässt sich dieser Link am besten über das Versionsverwaltungssystem und / oder das Fehlerverfolgungssystem erstellen. Voraussetzung dafür ist jedoch, dass Sie Ihren Code genau mit dem Bug-Tracker oder der Stelle im Versionsverwaltungssystem verknüpfen können, an der Sie Ihre Kommentare hinterlassen.


quelle
Das ist interessant: Sie schlagen also tatsächlich vor, dass ich im Falle einer SO-Antwort den HTML-Code abrufen und in meinem DVCS speichern könnte (Mercurial, aber das ist nicht der Punkt)?
Tristan St.
Normalerweise brauchst du nicht alles, nur die relevanten Teile, oder? Und Sie können die Quelle verweisen.
5

Im Idealfall benötigt Ihr Code keine derartigen Kommentare, da er gut strukturiert ist usw. Aber ja, wenn Ihre Situation nicht optimal ist, ist es akzeptabel , solche Kommentare einzutragen. Und Links zu stackoverflow.com sind genauso gut (und oft besser!) Wie andere.

Hoffentlich handelt es sich um temporäre Kommentare, und Sie können zurückkehren und den Code verbessern und diese Kommentare entfernen .

Ich habe noch keinen StackOverflow.com-Link in meinen Code eingefügt. Ich versuche, das Einfügen von Links in Code zu vermeiden, da es schlecht riecht, aber wenn es soweit ist, zögere ich nicht.

Bearbeiten : Ich denke, meine obige Antwort vermittelt den Eindruck, dass die Notwendigkeit für Kommentare wie diese vermeidbar ist. Natürlich ist es manchmal nicht vermeidbar; Es ist ein Fehler in einer Bibliothek oder in einem schlechten API-Design, über den Sie keine Kontrolle haben. Kommentare wie diese, einschließlich Links, sind für den nächsten Entwickler sehr hilfreich.

Patrick Karcher
quelle
2
hey, sieh dir das an, ich wünschte, es gäbe eine "sauberere" Möglichkeit, damit umzugehen, aber sehr oft ist es nicht der Fall stackoverflow.com/questions/951848 Ich meine, Bugs und Inkonsistenzen / seltsame API, undokumentiertes Verhalten usw. sind ein Teil unserer Programmierer Leben :)
Tristan St.
2

Ich betrachte es als würde ich eine Forschungsarbeit schreiben. Wenn ich die Ideen einer anderen Person verwende, muss ich diese Ideen würdigen. Ich habe zuvor in meinem Code eine Antwort von stackoverflow verwendet und den Link zu den Kommentaren der Methode hinzugefügt.

Wie bereits erwähnt, handelt es sich bei SO um einen Wiki-Stil. Es ist also möglich, dass er sich ändert, aber im Allgemeinen sollte die Idee immer noch dieselbe sein.

Sie sollten anderen trotzdem Ehre machen, wenn Sie ihre Ideen verwenden.

jmq
quelle
1

Wenn Sie eine Problemumgehung implementieren mussten und nicht klar ist, warum die Implementierung auf eine bestimmte Art und Weise erfolgt ist, sollten Sie einen Kommentar abgeben, um die Gründe dafür zu ermitteln. Ich halte es für in Ordnung, einen Link zu einer Online-Referenz zu setzen, aber Sie müssen Ihren Kommentar wirklich kurz und bündig formulieren, und dennoch so vollständig, dass der Link nur dann eine ausführliche Erklärung liefert, wenn der Leser das Gefühl hat, Ihre Argumentation noch einmal überprüfen zu müssen.

Wenn der Code hingegen wörtlich kopiert wurde, ist ein Link zur Originalquelle nur fair und kann abhängig vom Wortlaut der Lizenz erforderlich sein, unter der Sie das Werk des Originalautors kopieren dürfen.

S.Robins
quelle