Commentare il codice: metti i tuoi commenti di codice su Interfacce o su classi Concrete o entrambi?

Question

Qual è la migliore pratica nella documentazione di classi e interfacce. Di 'se hai una classe concreta chiamata Foo, che deriva da un'interfaccia chiamata IFoo. Dove metti i tuoi commenti per i tuoi metodi? Duplicate i vostri commenti sull'interfaccia e sulla classe concreta?

Ecco un esempio in cui vengono duplicati commenti:

public class Foo : IFoo 
{ 
    /// <summary> 
    /// This function does something 
    /// </summary>   
    public void DoSomething() 
    { 
    } 
} 

public interface IFoo 
{ 
    /// <summary> 
    /// This function does something 
    /// </summary>   
    void DoSomething(); 
} 

Answer 1

avrei messo i commenti su entrambi.

Sulle interfacce vorrei commentare l'intento dietro i membri dell'interfaccia e l'utilizzo.

Per le implementazioni vorrei commentare le ragioni della specifica implementazione.

Answer 2

io in genere li metto su entrambi, però, non dicono la stessa cosa. Il commento dell'interfaccia dovrebbe descrivere lo scopo astratto di questo metodo/interfaccia. Mentre il commento concreto parlerà delle specifiche di implementazione del metodo/classe nel contesto dello scopo dell'interfaccia.

Answer 3

Li ho messi in entrambi, ma è un problema tenerli sincronizzati, quando in dubbio li metto solo sull'interfaccia.

Lo faccio perché mi piace la descrizione comando quando si utilizza il codice, che dovrebbe essere quasi sempre utilizza l'interfaccia ...

Answer 4

Io in realtà non li uso affatto. Invece mi assicuro di strutturare il codice e nominare tutti i metodi e le variabili in modo che sia ovvio cosa fanno senza commenti. Il problema con i commenti è che non vengono compilati e non vengono eseguiti e non vengono testati dai test delle unità, quindi è praticamente impossibile mantenerli sincronizzati con il codice.

Answer 5

Solo per interfacce. Perché in questo caso non ho bisogno di sincronizzarli. Il mio IDE mi aiuta a vedere i commenti dell'interfaccia in classi concrete. E il generatore di documenti API fa lo stesso.

Answer 6

entrambi, ma mi piacerebbe che c'è stato costruito nel funzionalità per tenerli in sincronia

Answer 7

Il tuo codice di esempio non usa implementazione dell'interfaccia esplicita. Il client del tuo codice avrà bisogno di entrambi poiché può invocare il metodo tramite un oggetto di classe o un riferimento all'interfaccia. Con l'implementazione dell'interfaccia esplicita è possibile omettere il commento del metodo di classe poiché il client non può mai vederlo. Ciò presuppone che si stia utilizzando la documentazione XML per generare informazioni IntelliSense.

Answer 8

Un tag <referTo>System. .... </referTo> per collegare i commenti che sarebbe l'ideale

Answer 9

Idealmente, solo l'interfaccia deve essere documentata, in quanto definisce il contratto che ogni concreta attuazione deve soddisfare.