Surely I can’t be the only one who thinks that “
union/unionInPlace” is clearly, obviously, and measurably superior to “
formUnion/union” (or, even worse,
unioned). While I’m pleased with most of the Swift API design guidelines, there are just a few places it steps too far. Here are a few quick ways to improve the guidelines, IMO:
Remove “Prefer method and function names that make use sites form grammatical English phrases.” This isn’t Objective-C. It’s time to move on. This single guideline, while superficially lovely, is causing too much strain and pain in the language. Shoehorning code into grammatical English doesn’t benefit the code or make it more understandable.
Remove “Use the “ed/ing” rule to name the nonmutating counterpart of a mutating method, e.g. x.sort()/x.sorted() and x.append(y)/x.appending(y).” Here’s another pain point. Using “in place” reads better and makes more sense. This is a clear example of not, to steal a phrase, using terminology well.
Add “When creating mutating/non-mutating counterparts, prefer names that relate to each other and use the new `MutatingCounterpart` and `NonmutatingCounterpart` document comments to connect those items”. SE-0047 simplifies the entire cross-referencing situation without having to use “form” (or as it’s read more often, “from”, as in “fromMorePerfectUnion“), “ing”, or “ed”.
Add: “Prefer nouns for methods with no side effects (or only incidental ones, like logging) and verbs for methods with significant side-effects.” When taking side effects (or their lack) into account, you want to name verby things with verby names and nouny things with nouny names, but don’t be too prescriptive.
Got any other changes you’d want to see? Drop a comment, send an email, or tweet me.