Use prepositions in naming verb-phrase functions?

Question

When writing a library, designing a class or extending some existing API, we often need to express actions or relations involving noun entities:

• "Place the ball in the bin"
• "Obtain the coat for the client"

(I'm trying to use concrete examples without too many programming connotations here.)

at times, only the nouns are properly named, and then we write code such as: coats[client] (which could be a lookup using an index or a hash). At other times, we're writing an actual named function or method. And now we face a dilemma - which name do we go with?

cloackroom.obtain_coat(some_client);  /* vs */  cloackroom.obtain_coat_for(some_client);
red_ball.place(the_blue_bin);         /* vs */  red_ball.place_in(the_blue_bin); 

and if we're writing functions, these will be:

obtain_coat(some_client);             /* vs */  obtain_coat_for(some_client); 
place(discarded_ball, the_blue_bin);  /* vs */  place_in(discarded_ball, the_blue_bin);

I find myself torn between these two naming options:

• naming without a preposition vs
• naming with a preposition as a suffix (_in, _for etc.)

My dilemma is a combination of clarity/exactness-of-expression, aesthetics and succinctness. But other than succinctness which is obvious here, I can't even decide what's "better". Seeing just the method or function name, the suffix kind of irks me; but reading obtain_coat(some_client) is also aesthetically grating (as opposed to functions whose name is a transitive verb: refund(some_client)). On the other hand - a function is an action, so it makes sense to name it using just a verb, leaving the object-related prepositions for other syntactic elements. Some languages sorta-kinda support that, through named arguments:

ball.place(target_receptacle <- the_blue_bin)
obtain_coat(requisitor <- some_client)

but let's assume that's not available to us.

My question: If you've faced this dilemma when designing (or rather, naming) some API - what were your significant consideration for and against the use of prepositions?

Note: If you have a language-specific or language-category-specific answer, that's perfectly ok; like I said, language features seem to have impact on this choice.

Answer 1

The preposition is indeed very expressive. And expressiveness reduced the errors that are due to ambiguity or misunderstandings.

However, this expressivity is only granted for methods with a single argument. If you have more parameters, the advantage of prefix will be less obvious.

Then come the practical aspects: programmers who are not native speakers will start to wonder if it should be _in _on or _of or _for or _to. Or you may want to add a parameter to a function without prefix; or refactor the order of the parameters. And what about an optional/default parameter? The prefix approach creates in these circumstances a lot more question, hesitations and changes than the simpler approach.

Perhaps this is why so many projects and naming convention go for the more neutral and less expressive form without prefix.

But your concern is completely valid. There are a lot of programming language that use named parameters for exactly this reason. Your example in swift would for example look like:

cloackroom.obtainCoat(for:someClient);
red_ball.place(in:theBlueBin,with:leftHand,mode:swiftly);

Of course, if you have an API with prefix naming convention that you’d use in a language with named parameters, this could look very odd ;-) A reason more for avoiding ending prefixes in the method name?

Answer 2

I am for using prepositions when it makes sense. It helps make the code more readable, and with modern IDEs, type-ahead features make any ambiguity a non-issue.

• Prepositions can clarify the direction of processing: closet.obtain_coat_for(client) has different semantics from closet.obtain_coat_from(client).
• When your team all speaks the same verbal language, there is no question to the meaning of the API call.

The concerns about language are only pertinent in the following cases:

• Your API is pubic to be used by 3rd parties
• You are working in an open source project

Answer 3

I always preferred a programming style which is like the natural language.

For me as german native speaker it is normal to have only one word, combining preposition and verb. Please see LEA-Dictionary: to put inside = hineinlegen as an example. So I would prefer the version red_ball.place_in(the_blue_bin); or in german roterBall.legeIn(kasten).

For other countries this could be differnt and maybe confuse the reader. So I think the answer to your question is depending on the culture and language.