Documentazione getter e setter

Question

Per getter/setter semplici, come quello seguente, qual è il modo migliore per documentarlo?

public float getPrice() 
{ 
    return price; 
} 

Sono abbastanza rigorosi su standard di codifica, quindi il mio IDE mi mette in guardia circa i metodi non documentati pubbliche/protette.

Opzione 1:

/** 
* Get the price field. 
* 
* @return 
*/ 

Opzione 2:

/** 
* @return Price 
*/ 

O non documentare a tutti?

Answer 1

Scriverò il minimo indispensabile per mantenere calma la linter. Se è evidente che cosa il getter/setter è sempre/impostazione, userei po 'di documentazione copia-incolla che rende chiaro che niente di speciale sta accadendo:

/** 
* Simple getter. 
* @return Price 
*/ 

io personalmente considero troppi getter e setter per essere un odore di codice, in quanto è un possibile segno che non stai fornendo operazioni al livello corretto di astrazione (questo ovviamente non è sempre vero, ma una regola empirica).

Answer 2

Documentare l'interfaccia come se l'utente non fosse a conoscenza dell'implementazione. I documenti sono per i chiamanti del metodo, che non devono sapere o preoccuparsi di quale sia lo specifico stato interno, ma devono preoccuparsi di ciò che il metodo fa per loro.

Answer 3

ero alla ricerca di un modo standard per Doco funzioni fino a quando ho cercato SO e ho trovato persone che utilizzano: GhostDoc - http://submain.com/products/ghostdoc.aspx

E 'uno dei migliori strumenti di auto Doco là fuori e formati ciascuno dei vostri commenti allo stesso modo . La cosa migliore è che se i tuoi metodi sono giustamente nominati, allora non hai nemmeno bisogno di modificare il doco generato automaticamente come avrebbe senso.

Inoltre, i commenti vengono visualizzati quando si utilizza intellisense in modo da poter ricordare ciò che il codice fa un mese dopo averlo scritto! :)

GhostDocs farà questo alla vostra proprietà: (Ctrl + Shift + D)

/// <summary> 
    /// Gets the price. 
    /// </summary> 
    /// <returns></returns> 
    public float getPrice() 
    { 
     return price; 
    } 

Answer 4

Descrivere il minimo per un altro programmatore per capire ciò che il metodo fa o ritorni.

userei questo:

/** 
* @return the price. 
*/ 

o

/** 
* Returns the prize. 
* 
* @return the price. 
*/ 

Questo duplica lo stesso testo, ma potrebbe essere necessario se eri d'accordo su alcuni standard di codifica che richiedono una descrizione e non solo i tag.

Non vorrei menzionare che restituisce il prezzo campo, dal momento che descrive la rappresentazione interna.

Answer 5

Se "prezzo" è qualcosa di diverso dal valore più ovvio, il tuo commento dovrebbe descrivere cosa significa "Prezzo" e viene utilizzato, non solo come viene chiamato.

Alcuni esempi ipotetici:

• È il "prezzo lordo delle imposte" o il "prezzo tasse incluse"?
• È espresso in dollari, euro o sterline?
• È arrotondato al centesimo, 5 centesimi o dollari più vicino?
• Viene restituito un valore speciale per indicare un elemento gratuito (ad esempio 0.0f)?
• Un prezzo può essere "non inizializzato" e, in caso affermativo, quale valore viene restituito (ad esempio -1.0f)?

Per una buona percentuale di metodi e proprietà, c'è qualcosa si può dire che dice al lettore più che il nome dirà loro. Ciò farà risparmiare un sacco di tempo agli altri programmatori e ridurrà il rischio di bug. Anche se si limitasse a confermare le loro supposizioni/ipotesi, le farà comunque risparmiare tempo.

Nel caso di valori "semplici" che sono completamente auto-esplicativi (ad esempio Rectangle.Width), quindi non sprecare il vostro tempo digitando - AtomineerUtils creerà per voi quel livello di documentazione con un singolo tasto. (Il vantaggio di AtomineerUtils nel tuo caso è che supporta i formati di commenti XML Doxygen, Javadoc e Documentation e VB, C#, C++/CLI, C++ e C, in modo da poter mantenere il formato esistente riducendo al contempo il tempo speso per GhostDoc farà un lavoro simile, ma supporta solo la documentazione Xml per VB e C#)