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 (
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.