È corretto inserire un collegamento ai siti di domande e risposte nei commenti di un programma?

16

In un po 'di codebase puoi vedere commenti che affermano cose come:

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

Quindi ho alcune domande, ma sono tutte correlate.

È corretto inserire un collegamento a domande SO nei commenti di un programma:

 // 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 fai?

E quali sono gli svantaggi nel farlo? (vedi il mio primo commento per un terribile inconveniente)

comments

— Tristan St.
fonte

9

commentando me stesso: uno svantaggio molto preoccupante quando lo fai è che a causa del fatto che SO è un Wiki non c'è esattamente la garanzia zero che le risposte su cui fai affidamento saranno ancora corrette (o addirittura saranno ancora lì). Diamine, in alcuni casi la domanda stessa potrebbe essere chiusa o modificata dal suo significato originale. L'enorme differenza tra "Vedi bug 1434594" nella parata dei bug di Sun è che hai la garanzia che il testo del link bug di Sun non cambierà ( "non lo farà" come definito da RFC2119). Questo è enorme: il fatto che SO sia una wiki mi rende nervoso quando inserisco link SO nei commenti.

— Tristan St.

7

La tua scommessa migliore è quella di mettere un riassunto chiaro e conciso della risposta SO, quindi inserire il link di riferimento al di sotto di quello. L'ho fatto in diverse occasioni. In questo modo, se SO dovesse mai andare sotto o la risposta fosse rimossa / modificata, le informazioni di base che volevi sono ancora nel tuo riassunto. Ora, a seconda della complessità della risposta, scrivere il riassunto potrebbe essere un lavoro completamente separato. Se la risposta SO si collega a qualcos'altro, potrebbe valere la pena collegarla a quelle (specialmente se sono meno effimere delle risposte SO).

— FrustratedWithFormsDesigner,

5

@Robert S .: no, non è un meta. Non si tratta di SO: sto accettando SO così com'è. Si tratta in particolare di come gestire una risorsa simile a quella di un commento.

— Tristan St.

1

Stai parlando del codice che scrivi per la tua squadra? Chiediglielo.

1

Puoi sempre salvare l'intera pagina Web come pagina Web completa, comprimerla e inserirla nella cartella del documentario.

7

L'ho fatto, forse non specificamente per Stack Overflow, ma per blog tecnici, forum, Usenet, Google Gruppi o altri luoghi in cui il "perché l'ho fatto" potrebbe non essere completamente chiaro dal contesto.

Non vedo perché usare SO in questo modo sarebbe una brutta cosa, a meno che non archivino e cancellino le vecchie domande (cosa che non penso lo facciano, ma non ne sono sicuro) - ma anche se lo fanno, non è così peggio di qualsiasi altro sito.

Se sei davvero preoccupato per questo, puoi sempre prendere screenshot o scaricare queste pagine come testo (o passare attraverso il problema di ottenere immagini, fogli di stile, ecc.) E salvarli in un repository di conoscenze presso la tua azienda, allegando un identificatore univoco e inserendo quell'identificatore univoco nei tuoi commenti per consentirti di fare riferimento in un secondo momento, avresti un posto coerente per questo tipo di cose. Ma potrebbe essere eccessivo, a seconda della complessità e dell'importanza del codice.

— Joe Enos
fonte

5

Generalmente, il modo migliore per creare questo collegamento è attraverso il sistema di versioning e / o il sistema di tracciamento dei bug. Il requisito per farlo funzionare però è che puoi collegare accuratamente il tuo codice al tracker dei bug o alla posizione nel sistema di versioning in cui inserisci i tuoi commenti.

è interessante: quindi in realtà stai suggerendo che nel caso di una risposta SO potrei recuperare l'HTML e memorizzarlo nel mio DVCS (Mercurial ma non è questo il punto)?

— Tristan St.

Bene, normalmente non hai bisogno dell'intera cosa, solo i pezzi rilevanti giusto? E puoi fare riferimento alla fonte.

5

Idealmente il tuo codice non ha bisogno di tali commenti perché è ben strutturato, ecc. Ma sì, quando la tua situazione è meno che ideale, è accettabile inserire commenti come questo. E i collegamenti a stackoverflow.com sono altrettanto buoni (e spesso migliori!) Di altri.

Si spera che siano commenti temporanei e ti sarà permesso di tornare indietro e migliorare il codice ed estrarre questi commenti .

Non ho ancora inserito un link StackOverflow.com nel mio codice. Cerco di evitare di inserire collegamenti nel codice, dato che è un cattivo odore, ma quando arriva il momento non esiterò.

Modifica : penso che la mia risposta di cui sopra dia l'impressione che la necessità di commenti come questo sia evitabile. Certo a volte non è evitabile; è un bug in una libreria o un design API scadente su cui non hai alcun controllo. Commenti come questo, inclusi i collegamenti, sono molto utili per il prossimo sviluppatore.

— Patrick Karcher
fonte

2

ehi, guarda quello, vorrei che ci fosse un modo "più pulito" per gestirlo, ma molto spesso non è il caso stackoverflow.com/questions/951848 Voglio dire, bug e incongruenze / API strane, comportamento non documentato, ecc. fanno parte della nostra vita di programmatore :)

— Tristan St.,

2

Lo vedo come scrivere un documento di ricerca. Se uso le idee di qualcun altro, allora devo dare credito a quelle idee. Ho usato una risposta da StackOverflow nel mio codice prima e ho aggiunto il link ai commenti del metodo.

Come qualcuno ha detto, SO è uno stile wiki, quindi è possibile che possa cambiare, ma generalmente l'idea dovrebbe essere la stessa.

Dovresti comunque dare credito agli altri quando usi le loro idee.

— JMQ
fonte

1

Se è necessario implementare una soluzione alternativa e non è ovvio il motivo per cui l'implementazione è stata eseguita in un modo particolare, è necessario lasciare un commento per identificare i motivi. Penso che posizionare un collegamento a un riferimento online sia corretto, ma devi davvero aver reso il tuo commento breve, ma abbastanza completo che il collegamento fornirà solo una spiegazione estesa se il lettore dovesse sentire la necessità di ricontrollare il tuo ragionamento.

Se d'altra parte il codice è stato copiato alla lettera, allora un collegamento alla fonte originale è giusto, e potrebbe essere richiesto a seconda della formulazione della licenza con la quale ti è stato permesso di copiare il lavoro dell'autore originale.

— S.Robins
fonte