Riferimento alle domande StackOverflow nei commenti [duplicato]

0

Spesso durante la codifica mi trovo bloccato su un problema particolarmente difficile e cercherò una soluzione. Il più delle volte questo mi porta a una domanda StackOverflow che fornisce una soluzione completa o parziale, spesso con codice che può essere utilizzato direttamente incollando nel codice originale.

In alcuni casi questo può portare a un codice apparentemente non intuitivo o a cose apparentemente insolite - come sovraccaricare metodi esistenti nelle classi, reimplementare funzioni integrate con lo stesso nome o altrimenti rompere alcuni aspetti di "buone pratiche" per raggiungere una soluzione. A volte queste sembrano pratiche sbagliate, ma a causa di problemi nel codice

In casi come questi mi capita spesso di includere un link alla risposta che ho implementato, con qualche breve spiegazione piuttosto che riscrivere o duplicare spiegazioni dettagliate.

Includere gli URL alle soluzioni per questi tipi di problemi nei commenti è una pratica comune, oppure esiste un modo migliore per documentare questo tipo di codice?

Come esempio di questo tipo di problema, Di recente ho fatto una domanda sulla risoluzione di un conflitto con il decoratore di proprietà Python , dove la soluzione era quella di rinominare la funzione in-built di Python e incluso un link alla domanda nel codice .

    
posta Community 24.07.2014 - 07:04
fonte

2 risposte

4

Poiché i link possono essere infranti o altrimenti invalidati, non devi dipendere per la tua documentazione.

Se scrivi qualcosa di non ovvio basato su una risposta su StackOverflow o basato su qualche altro contenuto su Internet, allora dovresti includere abbastanza informazioni nella tua documentazione su cosa fa il codice e perché è scritto in quel modo che i futuri manutentori non bisogno di seguire i collegamenti, ma puoi capire il codice dalla sola documentazione.
Puoi sempre includere il link come luogo in cui ottenere maggiori informazioni. Può anche essere utile se si desidera verificare in un secondo momento se i consigli forniti al momento sono ancora considerati i migliori consigli oggi.

    
risposta data 24.07.2014 - 08:43
fonte
2

Lo faccio molto Scriverò commenti che collegano alle risposte SO, che collegano ai problemi di Github, che collegano qualsiasi cosa in cui si possano trovare maggiori informazioni sul problema / risposta specifici.

Ci sono avvertimenti a farlo:

  • Nel caso di domande SO, la domanda potrebbe essere cancellata o la risposta potrebbe essere modificata o cancellata e potrebbe non essere più pertinente;
  • Qualsiasi altro link può anche avere il suo contenuto modificato o essere rimosso del tutto.
risposta data 24.07.2014 - 07:11
fonte

Leggi altre domande sui tag