Birth of a Cargo Cult

Looking for the root cause of grammatical obsession that burdens our naming discussions, exploring the commit history proved quite illuminating. To support the fundamental value of ”Clarity at the point of use”, the Swift API Guidelines section on Naming elaborates how to achieve it using a set of principles presented in three groups.

There is a marked difference in tone between them, with second section consisting mainly of prescriptive rules about what grammatical forms to use when naming various kinds of methods or how to clearly distinguish protocols from other types. But the first principle therein is a notable exception. It isn’t phrased as a rule, but as an advise: “Prefer method and function names that make use sites form grammatical English phrases.”

It was originally part of the first group that’s framed in terms of principles you should consider while naming things. To apply them, you need to exercise sound judgment, as they can be in conflict. This is where the guideline about fluent interface originated.

The birth of the grammar cargo cult can be traced to the commit that moved it down, from the last place in the top section to the first place in the second. The second section was called “Be Grammatical” at that time. During the move a single word “grammatical” was inserted into it. That’s the moment when a nod to preferred programming style was recontextualized as a dogmatic rule, amplified by the power of implicit ordering in unordered lists. There must have been some back-and-forth about it, because the section was later renamed to “Strive for Fluent Usage”, but that subtlety remained lost on many in the years that followed.

What is your point ?

I think this is the point we can use to de-emphasize the focus from English grammar and bring it back to Fluent Interface as a way to achieve clarity at the use site when designing API, without getting side tracked into bikeshedding the grammar.

Basically something along these lines:

What do you think?

I think concrete specific suggestions with examples work best.

To add to that i don’t think it is important to tweak the wording of the api guidelines.

1 Like

Pavol opened four separate threads to discuss different aspects of what I think is really a single argument. I’m therefore going to lock this thread and recommend that any further conversation be taken to the thread with the most discussion.