Dovrei indicare che un metodo soddisfa un'interfaccia?

3

Quando scrivi una classe che ha ("soddisfa") 1 o più interfacce, dovrei notare in qualche modo (ad esempio in un commento XML o con un attributo) che è stato aggiunto un particolare metodo per una delle interfacce?

Ad esempio, l'interfaccia IComparable richiede un metodo int CompareTo(Object) .

So che non ho bisogno di fare qualcosa di diverso dall'implementare i metodi appropriati, ma per la manutenibilità e la facilità di comprensione ci sono delle "migliori pratiche" per far sapere agli altri perché il metodo esiste?

    
posta Dave 02.10.2014 - 18:33
fonte

3 risposte

0

Sì. La tua inclinazione è sana. Dovresti lasciare un commento nel codice sorgente del metodo e / o in una documentazione più ampia.

// Implements IComparable interface

nel metodo source dovrebbe fare il trucco, permettendo a coloro che leggeranno il codice da vicino (più tardi, o qualcun altro che lo mantenga, lo modifichi o lo adattino) per capire in modo semplice e rapido perché il metodo esiste.

Se il metodo fa parte di un'API promossa, può anche essere menzionato nei documenti API (la cui forma varia in base al sistema di documentazione che stai utilizzando).

Anche se non sei completamente impegnato a programmazione alfabetica , in cui una spiegazione del codice è considerata co- uguale al codice stesso, è una pratica eccellente usare i commenti nella fonte del programma e le note nella documentazione dell'API per spiegare come funziona il programma, perché è definito e implementato così com'è e come usarlo.

    
risposta data 03.10.2014 - 04:01
fonte
3

Non dovrebbe essere necessario trattare il metodo in modo diverso da qualsiasi altro. In questo esempio, un metodo denominato CompareTo() sarebbe ovvio per chiunque abbia un'esperienza .NET significativa come implementazione di IComparable<T> . L'idiota che lo commenta o lo elimina verrà informato dal compilatore che la classe non implementa più IComparable<T>.CompareTo() , e a quel punto dovrebbe capire che hanno incasinato e rimesso a posto. Il bozo totale che, ricevendo questo errore, pensa che la soluzione migliore sia rimuovere l'interfaccia IComparable<T> dalla definizione della classe (senza un inferno di una buona ragione, come se fosse tracciato ogni utilizzo della classe attraverso la tua base di codice ed è 100% positivo la classe non fa mai parte di alcuna operazione di ordinamento) probabilmente non ha bisogno di lavorare per la tua azienda.

Se vuoi essere gentile, //Implementation of IComparable<T> posizionato da qualche parte vicino alla dichiarazione della funzione (appena sopra di esso, o appena dentro il corpo della funzione) dovrebbe renderlo abbastanza chiaro anche per le teste di ossa menzionate sopra.

Se vuoi essere davvero gentile, puoi xml-doc la classe / metodo, e nel tag <remarks> , affermare che questo metodo è l'implementazione di IComparable<T> per la classe. Questo non verrà visualizzato solo in origine, ma anche in qualsiasi documentazione SandCastle creata. Potrebbe apparire in IntelliSense, ma ne dubito; le osservazioni possono essere piuttosto grandi. Se è assolutamente positivo conoscere tramite IntelliSense che il metodo è l'implementazione dell'interazione, menzionarlo nel tag <description> .

    
risposta data 03.10.2014 - 00:46
fonte
-1

Metti i metodi che soddisfano l'interfaccia in #region .

#region IMyInterface Members

// methods that satisfy interface

#endregion

Visual Studio ha anche una scorciatoia per creare questa regione e prototipi di metodi per ogni metodo nell'interfaccia, disponibile facendo clic con il pulsante destro del mouse sulla dichiarazione "eredita da" nella definizione della classe e selezionando "Implementa interfaccia".

In altre parole, Microsoft considera ciò una best practice.

Naturalmente, nulla ti impedisce di inserire un commento XML che dice "Questo metodo soddisfa le interfacce Iinterface1 e Iinterface2 ."

    
risposta data 02.10.2014 - 18:48
fonte

Leggi altre domande sui tag