Va bene inserire un collegamento a siti di domande e risposte nei commenti di un programma?

15

In un bel po 'di codebase puoi vedere commenti come:

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

Quindi ho alcune domande, ma sono tutte correlate.

Va bene inserire il link alle 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)

    
posta Tristan St. 17.05.2010 - 18:42
fonte

5 risposte

7

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

Non vedo perché usare SO come questo sarebbe una brutta cosa, a meno che non archivino e eliminino vecchie domande (che non penso che facciano, ma non ne sono sicuro) - ma anche se lo fanno , non è 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 le immagini, i fogli di stile, ecc.) e salvarli in un archivio di conoscenze della tua azienda , allegando un identificativo univoco ad esso e inserendo quell'identificatore univoco nei tuoi commenti per permetterti di fare riferimento in un secondo momento, allora avresti un posto coerente per questo tipo di cose. Ma potrebbe essere eccessivo, a seconda della complessità e dell'importanza del tuo codice.

    
risposta data 17.05.2010 - 18:47
fonte
5

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

    
risposta data 17.05.2010 - 18:46
fonte
5

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

Speriamo che siano commenti temporanei, e ti sarà permesso di tornare indietro e migliorare il codice e prendere questi commenti .

Non ho ancora inserito un link StackOverflow.com nel mio codice. Cerco di evitare di mettere i link nel codice, dal momento che è un cattivo odore, ma quando verrà il momento non esiterò.

Modifica : penso che la mia risposta sopra riportata dia l'impressione che la necessità di commenti come questo sia evitabile. Ovviamente a volte è non evitabile; si tratta di un bug in una libreria o di una scarsa progettazione dell'API su cui non si ha alcun controllo. Commenti come questo, inclusi i link, sono molto utili per il prossimo sviluppatore.

    
risposta data 17.05.2010 - 18:45
fonte
2

Lo vedo come se stessi scrivendo un documento di ricerca. Se uso le idee di qualcun altro, allora ho bisogno di dare credito a quelle idee. Ho già usato una risposta da stackoverflow nel mio codice 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 sempre la stessa.

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

    
risposta data 03.02.2012 - 10:03
fonte
1

Se hai bisogno di implementare un work-around, e non è ovvio perché l'implementazione è stata fatta in un modo particolare, allora un commento dovrebbe essere lasciato a identificare i motivi per cui. Penso che posizionare un collegamento a un riferimento online sia corretto, ma è davvero necessario che il commento sia succinto, ma sufficientemente completo che il collegamento fornirà una spiegazione ampliata nel caso in cui il lettore sentisse la necessità di ricontrollare il proprio ragionamento.

Se d'altra parte il codice è stato copiato letteralmente, allora un link alla fonte originale è giusto e può essere richiesto a seconda del testo della licenza in base al quale ti è stato permesso di copiare il lavoro dell'autore originale.

    
risposta data 03.02.2012 - 11:16
fonte

Leggi altre domande sui tag