Devo fornire sinonimi in un'API?

5

Sto progettando una piccola libreria e c'è una strong tentazione di fornire sinonimi ad alcune delle funzioni esportate.

var foldl = function(){ ... };
var reduce = foldl; //reduce is a synonym for foldl

Immagino che i nomi multipli possano aiutare l'apprendimento iniziale dell'API (poiché è più probabile che l'utente inciampi nella funzione che desidera) ma allo stesso tempo mi preoccupo che la duplicazione porterà complessità inutile.

Quali regole dovrei tenere a mente quando penso di aggiungere un sinonimo a una funzione nella mia API?

Quando dovrei scegliere un "c'è più di un modo per farlo" api e quando dovrei incentivare c'è un modo per farlo "invece?

    
posta hugomg 12.12.2011 - 16:57
fonte

3 risposte

25

Non fornire più modi per fare la stessa cosa: ciò confonderà solo gli utenti dell'API.

Avere più nomi per le stesse cose significa che non hai un buon nome per questo.

    
risposta data 12.12.2011 - 17:00
fonte
2

Non è solo confuso usare più nomi per la stessa cosa, ma questo inquinerà anche lo spazio dei nomi di chi sta usando la tua API. In c # sono spesso torturato dal fatto di non poter denominare le mie variabili come default o spuntato = P. Conoscendo un po 'di Perl, la mia intuizione è anche che le funzioni che sembrano fare la stessa cosa sono in genere sottilmente diverse (chop, chomp).

    
risposta data 12.12.2011 - 23:32
fonte
1

Usane uno. L'unica situazione a cui riesco a pensare dove vuoi entrambi è se ci sono due domini aziendali separati che richiedono la stessa funzione in questo momento, ma potrebbero dividersi più tardi. So che è YAGNI, ma se lo stanno "considerando" in questo momento, potresti volerlo pensare.

    
risposta data 12.12.2011 - 18:21
fonte

Leggi altre domande sui tag