Sono in procinto di scrivere la mia prima vera API. Nel processo, sto definendo un'interfaccia per mappare strutture dati complesse su altre strutture dati complesse.
Al momento, l'interfaccia contiene un metodo set per la struttura dei dati di input, un metodo run per avviare il processo di mappatura e diversi metodi che hanno fondamentalmente la stessa firma, ma ovviamente nomi diversi e diversi documentazione. Questi ultimi restituiscono java.lang.Object . Qualcosa come segue.
public interface DataCompiler {
public void setInputDataStructure(IDS ids);
public void run();
/**
* Maps a "this" structure to a target "this" structure and
* returns the resulting target "this" structure.
*/
public Object mapThisStructure();
/**
* Maps a "that" structure to a target "that" structure and
* returns the resulting target "that" structure.
*/
public Object mapThatStructure();
/**
* Maps an "other" structure to a target "other" structure and
* returns the resulting target "other" structure.
*/
public Object mapOtherStructure();
}
Quindi, un'interfaccia è pensata per definire un contratto che deve essere soddisfatto dalle implementazioni dell'interfaccia.
Tuttavia, con la mia interfaccia non vi è alcun accorgimento di sicurezza nelle firme del metodo stesso per impedire l'uso improprio di uno degli ultimi tre metodi. Ad esempio, mapThisStructure potrebbe effettivamente essere implementato nel modo esatto in cui mapThatStructure è significato da implementare. Oppure, qualcuno potrebbe mettere tutto il lavoro di mappatura in uno dei tre mappaggi (il che ovviamente infrangerebbe il principio di un metodo che fa una e una sola cosa ), e lascia semplicemente che gli altri due restituiscano null .
Quindi il contratto effettivo è definito nel JavaDoc. Quindi, l'impostazione di tale interfaccia ha senso?