Funzione ridondante per chiarire lo scopo? [duplicare]

1

Poiché ciò che conta non è come il codice lo fa, ma cosa fa, prenderebbe in considerazione di avvolgere una funzione con un nome diverso solo per chiarire il suo comportamento in determinate situazioni una buona pratica?

Esempio di vita reale con pseudo-codice:

Diciamo che ho un piccolo modulo per generare segnali hardware. Ora naturalmente ci si aspetta di trovare da qualche parte nell'API una funzione per avviare un segnale una volta che tutte le configurazioni sono state fatte e l'hardware è pronto a sparare:

startSignal(myProperlyConfiguredInstance);

Ora, il mio utente si chiederà naturalmente cosa succede se questa funzione viene chiamata più volte.

  • Il codice rileva che il segnale è in esecuzione e ignora la chiamata?
  • Genera un'eccezione perché presuppone che sia un errore provare ad avviare il segnale più volte?
  • Causa problemi hardware?
  • Viene ripristinato l'hardware e viene avviato un nuovo segnale?

La risposta ovvia sembra essere "il comportamento specifico dovrebbe essere presente nel documento", ma sappiamo tutti come la documentazione sembra decadere più velocemente di quanto non lo scriviamo e il codice è migliore di quello della clear doc.

La mia soluzione a questo problema era di fare questo:

void restartSignal(Instance myInstance){ 
    startSignal(myInstance);

}

Ora mi sembra che sia chiaro che il comportamento previsto è il 4 ° punto e il mio utente non deve porsi questa domanda; può semplicemente chiamare il riavvio se il segnale è in esecuzione o se non lo è.

Ma ora ho un codice ridondante che in realtà non complica nulla? Sembra che mi sto ripetendo ed è perfettamente corretto chiamare il riavvio per avviare un segnale di inattività e avviare un segnale in esecuzione!

Quale preferisci? API più ricca rispetto all'API più semplice che richiede un picco nel doc / test / codice sorgente?

    
posta Asics 03.07.2014 - 22:11
fonte

3 risposte

6

would you consider wrapping a function with a different name just to clarify it's behavior in certain situations a good practice?

Assolutamente.

La cosa fondamentale qui è che per quasi tutto il codice, l'interfaccia conta più dell'implementazione . Se ha senso avere un metodo Restart nell'interfaccia, quindi aggiungilo. Perché mentre è vero che per questa classe, oggi le implementazioni sono le stesse ... non è esattamente raro che le altre implementazioni dell'interfaccia differiscano o cambino i requisiti in causa l'allontanamento delle implementazioni.

Tutto ciò che ho detto, lo farei come relativamente l'ultima risorsa. Avere due metodi diversi che fanno la stessa cosa è un segno che il mio design / denominazione è scadente. Gli utenti dell'interfaccia pensano spesso "Qual è la differenza tra queste cose?".

    
risposta data 03.07.2014 - 22:36
fonte
1

In generale, sono contraria a scrivere un metodo con un nome semanticamente diverso che chiama semplicemente un altro metodo, ma non ha un comportamento diverso, a meno che non stia implementando il Pattern Adattatore .

L'unico modo in cui potrebbe avere senso è se si assegna al metodo qualcosa del tipo:

restartSignalIsReallyJustAStart()

che spiega completamente cosa stai facendo senza fare il programmatore dopo ti chiedi perché hai scritto un altro metodo con un nome diverso che non fa altro che chiamare il metodo originale.

... tranne che è piuttosto ridicolo, non è vero? Evita questo, e assicurati di avere una buona documentazione che spieghi perché "start" e "restart" sono la stessa cosa.

Ulteriori letture
È una buona idea fornire diverse firme di funzioni che stessa cosa?

    
risposta data 03.07.2014 - 22:17
fonte
0

Mi piace la domanda. È sicuramente un'idea che merita qualche riflessione. Ho ho visto un codice simile in natura, ma solo in casi come restart che fa parte di un'interfaccia pubblica che stai implementando per uno dei numerosi chip, alcuni dei quali richiedono logica diversa per eseguire una pulizia restart.

Per amor di discussione, supponiamo per un momento che la tua intenzione di aggiungere restart fosse completamente chiara a tutti i futuri manutentori, che probabilmente non è un'ipotesi valida considerando tutta la confusione solo da parte di persone che commentano questa domanda.

Non hai ancora raggiunto i tuoi obiettivi iniziali, poiché molte domande aperte rimangono solo guardando le firme delle funzioni e potresti averne persino creato di nuove. Le tue prime due domande sono ancora molto valide. Non sai ancora cosa succede se chiami start due volte. In effetti, aggiungere restart mi renderebbe più cauto nel chiamare accidentalmente start due volte. Quanto è importante verificare se è già stato avviato prima di chiamare start ?

Le tue seconde due domande sono appena state spostate nella funzione restart . Non hai ancora comunicato se un riavvio causa problemi tecnici, un arresto completo e il riavvio, o qualsiasi altra cosa.

Alla fine, non puoi evitare di documentare certi aspetti del tuo codice nei commenti. Non confondere l'ammonizione per evitare commenti eccessivi come monito a non commentare mai. Il tipo di domande che hai menzionato sono perfette per i documenti API.

    
risposta data 03.07.2014 - 22:48
fonte

Leggi altre domande sui tag