Take the 2-minute tour ×
Programmers Stack Exchange is a question and answer site for professional programmers interested in conceptual questions about software development. It's 100% free, no registration required.

My question will be about how do you think it would be fit to name some methods in a fluent interface. Let me try to demonstrate the problem.

Consider this relation tree:

associations

A person can have dogs and cats, and a dog can have bones. Pretty simple.

What i'm trying to do is create a domain specific fluent interface for determining, which ones of these relations does the user need. It is able to handle any depth of relationships.

I designed the operation something like this (It is building the assoicaiton tree, from which i can determine, what the user wants): association tree building

As code (it may be more readable):

personAssoc = person.associate().withCats().and().withDogs().withBones().up().done(); 

But i'm trying to make this part as intuitive as possible, so i wan't the method names to make sense after each other, and be as close to spoken language as possible. My biggest concerns are the following 3 method names:

  1. and() in my language of choice and is a reserved keyword, so i can't use it. I looked up synonyms (together(), including(), also()) but they don't sound/look right (and means, that we will add more children to the parent association).
  2. up() it is obviously breaking any kind of flow. With this method name, the whole thing became a lot further away from spoken language, than i wanted to (up means, we are not necessary wan't to add more relations to the parent, but we are done with the current one. In code it is the same as and).
  3. done() is only called once, at the end of the method calls, but still doesn't fit the picture (done means, that we are literally done, we won't add more associations).

What i'm looking for is other, better names for the above 3, which:

  1. Which make the usage of the fluent interface closer to spoken language.
  2. For and a name, which is as far as possible from any language keywords.

If you read this whole thing, feel free to drop by any ideas, it might help me out a great deal! Thank you for any suggestion.

share|improve this question

closed as primarily opinion-based by gnat, MichaelT, Dan Pichelman, World Engineer Apr 13 at 2:47

Many good questions generate some degree of opinion based on expert experience, but answers to this question will tend to be almost entirely based on opinions, rather than facts, references, or specific expertise.If this question can be reworded to fit the rules in the help center, please edit the question.

    
that looks like a horrible idea, no offense, the method names don't really relate to what it's doing, only to how good it looks being used in a particular way. –  ratchet freak Apr 12 at 18:36
    
thanks for your reply, I'm open to anything, to make it as readable as possible. Please, if you have any suggestions, dont hold it back :) –  bali182 Apr 12 at 18:43

3 Answers 3

up vote 3 down vote accepted

There are two issues here: good naming, and the abuse of fluent interfaces.

A good API has two jobs: It must be straightforward to write code using this API, and the function of the resulting code should be obvious to a reader. While fluent interfaces excel in the latter matter, languages that try to be overly English-like fail the former requirement. Any API is a language that has to be learnt, so it should be as unsurprising as possible in order for a user to learn quickly.

I would therefore suggest that you do use a fluent API, but toned down to handle only one level of hierarchy at a time:

Person p = makePerson()
  .with(makeDog().with(makeBone()))
  .with(makeCat())
  .finish();

where PersonBuilder#with is overloaded to handle arguments of types Dog, DogBuilder, Cat, and CatBuilder etc.

If you absolutely must use a single level, I would like to suggest end, finish, or back instead of and. Using proper indentation would also help in making the code clearer:

person.associate()
  .withDog()
     .withBone()
     .end()
  .end()
  .withCat()
  .end()
.end()

This does not make it more English-like, but it follows clear rules (any with is mirrored by an end) and looks familiar to any programmer (and especially to anyone who has seen Ruby).

share|improve this answer

well, "with" is a awkward name... "has" is a much better one. Has and Is are very well established terms, as is Get. You should use those terms as it makes discoverability easier - people are familiar with GetParent for example as returning a parent object. This makes it a good term to keep using.

'And' seems to be "return parent", but in your naming convention, might be better described as "owner", so getOwner() or whoseOwner() might fit better.

Then you have

person.associate().hasCats().whoseOwner().hasDogs().hasBones().whoseOwner().disassociate()

disassociate seems like the opposite of associate - but both are artificial terms, it might be better to choose something less 'in keeping' with the tree and use a term that says "start processing" or similar, so you know its part of the plumbing.

share|improve this answer
    
I really like the owner thing. As for is and has, i feel like they should return a boolean (true/false) value, don't you think? It feels weirder for me, than with. For now, i leave the question open, but with owner you helped a lot, that was exactly what i was looking for to replace and, thank you! –  bali182 Apr 12 at 19:02

your proposed method just doesn't look maintainable to me

it's much easier to give Person a addCat and addDog method that does just that

Dog dog = new Dog();
dog.addBone();
person.addDog(dog);

this way you can also create the dog with its bones somewhere else without passing person to the bone factory.

share|improve this answer
    
no no, you misunderstood the purpose of the whole thing, maybe, the name person is misleadig. I don't retrieve data with the method call series above, i build some kind of hierarchy-descriptor-tree, which will help me retrieve the data. So here we can't talk about concrete Dog or Person instances –  bali182 Apr 12 at 18:54

Not the answer you're looking for? Browse other questions tagged or ask your own question.