Devo aggiungere note MSDN o collegamenti Stack Overflow al codice sorgente? [duplicare]

Naviga le tue risposte
7

Sto creando un host PowerShell / C # e voglio aggiungere il seguente commento 

// This method cannot be called multiple times on a given pipeline. The state of the 
// pipeline must be NotStarted when Invoke is called. When this method is called, it
// changes the state of the pipeline to Running. 
// see http://msdn.microsoft.com/en-us/library/windows/desktop/ms569128(v=vs.85).aspx
if (pipeline.PipelineStateInfo.State == PipelineState.NotStarted)
{
    Collection<PSObject> results = pipeline.Invoke();
}

Questo è un commento appropriato? Cosa miglioreresti a riguardo?

    
posta random65537 11.02.2012 - 16:33
fonte

6 risposte

12

Un link esterno va bene, forse con una breve sinossi sul perché detto link è interessante. Se possibile, mantenere l'intero commento su una singola riga.

Se temi che il link non sia più valido in futuro, crea una copia locale della pagina Web (Internet Explorer consente di salvare un'intera pagina web incluse le immagini in un unico file) e inserisci il file nella cartella della documentazione e nel link a quello.

    
risposta data 11.02.2012 - 16:36
fonte
7

Il punto di un commento è spiegare perché qualcosa è codificato così com'è. Il tuo commento è una buona spiegazione del motivo per cui hai un controllo extra dello stato della pipeline.

Penso che il collegamento sia ridondante, perché punta semplicemente alla versione corrente della documentazione per il metodo Invoke . A meno che il tuo editore non abbia il supporto per fare clic su tali link http, penso che sia più veloce premere semplicemente F1 sul metodo Invoke per visualizzare la sua documentazione. I collegamenti potrebbero anche cambiare e utilizzare il sistema di guida per ottenere la documentazione di un metodo sembra il modo più naturale per ottenere le informazioni più aggiornate su un metodo.

Tuttavia, le cose sarebbero diverse se si trattasse di un collegamento a una domanda Stack Overflow o di un'altra fonte che risolve un problema specifico che hai avuto con un pezzo di codice, ad es. informazioni oltre a quelle fornite nella documentazione ufficiale. Soprattutto se ti ci vuole un po 'per trovare online, potrebbe valere la pena di mantenere il link ad esso nel tuo codice. Ma dal momento che nemmeno i post di Stack Overflow non sono garantiti per essere in giro per sempre, fare una copia locale del post potrebbe essere più ragionevole se l'informazione è fondamentale per capire un pezzo di codice.

    
risposta data 11.02.2012 - 16:48
fonte
5

È sempre bello trovare un breve commento dove è necessario. Sostengo i miei compagni di squadra quando posizionano un collegamento ipertestuale a una buona fonte di conoscenza invece di scrivere una lunga storia su cosa sta succedendo qui. Questo approccio pulisce il tuo codice e mantiene il tuo commento aggiornato.

    
risposta data 11.02.2012 - 17:06
fonte
1

Il tuo commento non è necessario in quanto il codice è abbastanza chiaro da spiegare che non farà nulla se lo stato non è NotStarted. Se viene chiamato più volte, non ha alcun effetto. Forse dovresti considerare il nome del metodo per descrivere chiaramente l'intento del tuo metodo.

Nel caso separato di inserire riferimenti nel tuo codice, allora sì aggiungili se aggiungono veramente valore.

    
risposta data 11.02.2012 - 16:52
fonte
1

Sì.

L'aggiunta di link al tuo codice è un'ottima pratica e ciò che lo rende migliore è che stai spiegando il tuo ragionamento per farlo.

Una cosa che vorrei migliorare riguardo al commento è lasciare uno spazio tra il link e il commento per una migliore leggibilità.

Un'altra pratica (alternativa) sarebbe, oltre a aggiungere il collegamento, rendere il tuo commento un estratto dell'articolo.

    
risposta data 11.02.2012 - 20:10
fonte
1

Se si programma non banale, allora il tuo codice deve stare da solo e superare le prove del tempo. Se il codice sorgente viene perso, allora non verrà modificato e letto, ma in caso contrario il codice può sopravvivere per un tempo molto lungo. Alcuni degli utenti SO più anziani avranno storie sul codice che dura da diversi decenni.

Ho lavorato su sistemi che erano ancora in sviluppo attivo dopo decenni. I collegamenti ai siti Web sarebbero ben interrotti dal momento in cui un nuovo programmatore voleva leggerli.

Poiché non è garantito che MSDN o SO siano presenti, tutto ciò che fa un link è irritante.

Sir Tim Berners Lee ha scritto un appello molto appassionato affinché gli URL siano costanti, in modo che i collegamenti abbiano valore in futuro. Finora, non così tanto successo. Forse saremmo stati meglio se avesse brevettato il web e ci avesse obbligato a farlo a modo suo come parte dei termini della licenza?

    
risposta data 13.02.2012 - 01:10
fonte

Leggi altre domande sui tag

Tutte le funzioni ricorsive possono essere codificate con iterazioni? [chiuso] Oltre al kernel Linux, quale kernel del sistema operativo dovresti studiare? [chiuso]