Ho bisogno di consigli per la denominazione dei metodi wordy

Question

Sto scrivendo un'API per la creazione di forme geometriche e sto incontrando alcune difficoltà nel nominare i miei metodi.

Prendiamo un caso semplice: creazione di un cerchio. Molti di noi potrebbero avere familiarità con un metodo come graphics.drawEllipse(x, y, w, h). Per disegnare un cerchio, devi conoscere la coordinata in alto a sinistra, la larghezza e l'altezza del cerchio.

La mia API ha lo scopo di facilitare lo sviluppo di forme da parte di uno sviluppatore utilizzando una varietà di informazioni, senza eseguire molti calcoli matematici, cosa banale per le cerchie, ma più complicata per altre forme. Ad esempio, dovresti anche essere in grado di disegnare un cerchio in base alle coordinate e al raggio del centro o alle coordinate in alto a sinistra e in basso a destra.

Così Ho una classe Circle con metodi di fabbrica come:

Circle.createWithCenterAndRadius(cx, cy, r) 
Circle.createWithBoundingBox(x1, y1, x2, y2) 
Circle.createWithWidthAndHeight(x, y, w, h) 

Mi sento come se ci potrebbe essere un "codice di odore" qui, ma non sono sicuro. Da un lato, questi metodi di produzione sono necessariamente descrittivi. D'altra parte, posso prevedere che questi nomi di metodo sfuggano al controllo. Ad esempio, come dovrei denominare un metodo di fabbrica Triangolo che crea un triangolo dato un punto, la lunghezza di un lato, un angolo e la lunghezza di un altro lato? Triangle.createWithPointSideAngleAndSide(x, y, side1, angle, side2)? È solo cattivo?

Se si dovesse utilizzare questa API, i nomi dei metodi come questo vanno bene per te? Hai dei consigli su come posso rendere più sani i nomi dei metodi?

Answer 1

Sì, questa è più di una meta-risposta, ma ti suggerisco di dare un'occhiata a come viene effettuata la denominazione in Apple's Cocoa.

Answer 2

Va bene in qualsiasi lingua che non supporta i parametri denominati. Se la lingua supporta i parametri denominati, mi piace di più la creazione breve e solo i nomi dei parametri ovvi.

Per una lingua con parametri denominati, si farebbe:

Circle.Create(
    centerX = cx, 
    centerY = cy, 
    radius = r 
); 

Un'altra opzione più coinvolto, sarebbe un'interfaccia fluida simile (ma che probabilmente è troppo):

circleBuilder.Center(cx,cy).Radius(r) 
circleBuilder.Center(x,y).Width(w).Height(y) 
circleBuilder.BoundWith().Left(x1,y1).Right(x2,y2) 

rendimenti Centro un'istanza di una classe intermedia che consente solo Raggio o Larghezza. E BoundWith ne restituisce uno che consente solo Sinistra.

Answer 3

Si potrebbe modificare i vostri metodi cerchio di

Circle.FromCenterAndRadius(...) 
Circle.FromBoundingBox(...) 
Circle.FromWidthAndHeight(...) 

Ciò implica che si sta creando cerchi da loro diverse rappresentazioni in una sorta di modo conciso ...

Answer 4

Per le lingue che non supportano parametri nominati, sarebbe più pulito rendere il nome del metodo qualcosa di molto semplice come Circle.create e quindi aggiungere semplicemente una stringa di flag di input aggiuntiva (come "center" o "bounding") che indicava come i valori di input dovevano essere interpretati per casi che sono difficili da discriminare basandosi solo sull'input v numero e tipo di ariable? I svantaggi di ciò consistono nel fatto che richiede una logica extra all'interno del metodo per gestire diversi tipi di argomenti di input e richiede inoltre che l'utente ricordi le opzioni di flag.

Answer 5

Avrei i metodi CreateTriangle e il sovraccarico mostra le diverse informazioni richieste.

E.g.

Circle.CreateCircle(cx, cy, r) 
Circle.CreateCircle(point1, point2) 
Circle.CreateCircle(point, width, height) 

Answer 6

penso che ci sia niente di sbagliato con i vostri metodi descrittivi - sono la compatta e descrivere esattamente cosa sta succedendo. Gli utenti della biblioteca non avranno dubbi sulla funzione dei tuoi metodi, né sui programmatori di manutenzione.

Si potrebbe anche applicare qualche schema di progettazione qui se si è veramente preoccupati di esporre un gran numero di metodi di fabbrica, come avere metodi di fabbrica con classi di proprietà. Si potrebbe avere una classe CircleProperties con proprietà come CenterX, CenterY, Radius, (bool) UseCenterX, (bool) UseCenterY ecc e quindi si passa al metodo factory pubblico che determinerà quale metodo (privato) di fabbrica utilizzare.

Supponendo che C#:

var circleProperties = new CircleProperties() 
{ 
    CenterX = 10, 
    CenterY = -5, 
    Radius = 8, 
    UseCenterX = true, 
    UseCenterY = true, 
    UseCenterRadius = true 
}; 

var circle = Circle.Create(circleProperties); 

Answer 7

Il mio primo istinto è quello di avere più tipi, che consentirebbe per il metodo più intuitivo sovraccarico.

// instead of Circle.createWithCenterAndRadius(cx, cy, r) 
Circle.create(new Point(cx,xy), r); 

// instead of Circle.createWithBoundingBox(x1, y1, x2, y2) 
Circle.create(new Point(x1,y1), new Point(x1,y1)); 
// or even... 
Circle.create(new Box(p1,p2)); 

// instead of Circle.createWithWidthAndHeight(x, y, w, h) 
Circle.create(new Point(x,y), w, h); 

Così come Point, è possibile definire Distanza (che consentirebbe di diverse unità)

Se questo stile vi si addice, prendere in considerazione perché avete bisogno di un metodo di fabbrica invece di un costruttore.

Circle c = new Circle(new Point(cx,xy), r); 

Answer 8

Lo so, lo so. Questo suona completamente pazzo per te C/C++/Java, ma gli esempi forniti nella domanda e in tutte quelle risposte dimostrano chiaramente che una convenzione cattiva e cattiva CamelCaseNaming è davvero.

Diamo un altro sguardo l'esempio originale:

Circle.createWithCenterAndRadius(cx, cy, r) 
Circle.createWithBoundingBox(x1, y1, x2, y2) 
Circle.createWithWidthAndHeight(x, y, w, h) 

E ora cerchiamo di sbarazzarsi di quel caso cammello notazione

Circle.create_with_center_and_radius(cx, cy, r) 
Circle.create_with_bounding_box(x1, y1, x2, y2) 
Circle.create_with_width_and_height(x, y, w, h) 

Questo può sembrare terribilmente unfamilar, ma onesti: quale versione è più facile da leggere?

Answer 9

Il tuo istinto è corretto - l'intero schema di creazione delle cose in questo modo è - incerto.

A meno che non vengano utilizzati solo una o due volte, diventeranno piuttosto disordinati. Se stessimo creando una forma con 5 cerchi e 3 triangoli, sarebbe un disastro.

Tutto ciò che va al di là di un semplice esempio potrebbe essere fatto meglio con una sorta di implementazione basata sui dati.

Verso quelle estremità, avere una stringa, un hash o XML per definire le forme potrebbe essere estremamente utile.

Ma tutto dipende da come ci si aspetta che vengano utilizzati.

Ho lo stesso tipo di problemi con la creazione di controlli Swing in Java. Si finisce con una riga dopo l'altra di "new Button()" seguito da un gruppo di chiamate di proprietà .set nonché una riga di codice per copiare il valore in un oggetto (o aggiungere un listener) e una riga per reimpostare il valore..

Questo tipo di piastra non dovrebbe mai accadere nel codice, quindi di solito cerco di trovare un modo per guidarlo con i dati, legando i controlli agli oggetti dinamicamente - e verso tale fine, un linguaggio descrittivo basato su stringhe sarebbe molto utile.