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, unioning or 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.
10 Comments
Please do not present your opinions as “clear examples”, that “[read] better and [make] more sense”. What you perceive as “clear” and “better” is within you, not universal, and even you can change.
Yeah, the ed/ing thing bothers me, it is too much english-based. What about the MANY people who don’t speak fluent english (or at all) who want to learn programming, like I did when I was 10 ? Using some grammar stuff that might be irregular sometimes is weird. When is it “ed” ? When is it “ing” ?
Adding a word to the same method name is much clearer: “baseName” / “baseNameCaptitalizedModifier” is much easier to differentiate than a 2-3 lower case letters addition that gets lost in the name.
Also, it kind of favors the immutable one but that’s not really important.
And leaves names that make non sense to make mutable alone.
Like map(A->B) [A].reduce(A){…} etc.
“Prefer method and function names that make use sites form grammatical English phrases.” greetings from cblas_cher2k(_:_:_:_:_:_:_:_:_:_:_:_:_:) and makeDate(_:_:_:)
Are those actual functions???? Geez.
SE-0047 really nails it for me. It should be pretty hard to confuse mutating/non-mutating methods when you have to decide whether or not to put their result into a variable. In any case you get a warning (either for using a Void result or for ignoring an important result) that tells you you’re probably doing the wrong thing here.
If we were really confident on programmer’s capabilities we might even use the same name for both methods and let the return value decide which one to use, but I think that might be taking it a bit too far (especially with swift’s occasional type inference problems). Something to think about, though.
At some point, there were plans on allowing a notation like
var array = [1, 3, 2, 7, 0]
array.=sort() // `.=` tries to look up a `mutating` method
as the language syntax for calling
mutating func sort()if it was implemented; otherwisearray = array.sort()
I think it would be easier to adopt a language change like that if we preferred to use the (imperative tense) verb name for non-mutating methods from now on.
I can see how the current “ing/ed” naming convention can make sense for reference types. But for value types, I’d rather have mutation look like something serious might be happening.
And while we’re at it can we have “let mutable” instead of “var”?
[Yeah, it’s been brought up before but almost always dismissed because we already use “?” and “!”, but bear with me…]
Taking a leaf from the Ruby (and Scheme, for that matter – that’s where it came from) playbook where a postfix “!” (as part of the method name/identifier) is used to indicate that a method “does something dangerous”. Most often it is used to indicate a mutable variant method, but the postfix “!” is seen in some other contexts as a warning, and sometimes even when there is no immutable variant).
Using a postfix sigil of some sort to indicate “mutability or caution” seems like an ideal solution. There’s no longer a need to find “grammatically correct” variations on names, and it’s immediately clear to developers (regardless of native language) that “hey, this method has a side-effect that I should be aware of/wary of”.
If you’re OK with this idea so far, the next step is then – what sigil or character can we use? There’s a whole swag of Unicode character glyphs that we have access to. The Swift grammar segregates these into “identifiers” and “operators”. However, recognising a specific character as an identifier rather than an operator, should (AFAICT) be a relatively minor change to the grammar.
Since “?” and “!” already have meaning in Swift, and also “although operators can contain an exclamation mark (!), postfix operators cannot begin with either a question mark or an exclamation mark” [https://developer.apple.com/library/ios/documentation/Swift/Conceptual/Swift_Programming_Language/LexicalStructure.html#//apple_ref/doc/uid/TP40014097-CH30-ID418] we can’t use either of them. That’s unfortunate, but not really a showstopper.
But we can use both of them – at the same time – thus, the interrobang: ‽
Why?
* It has no meaning in mathematical notation (at least, as far as I’m aware), so it could apply equally well to mathematical constructs (unending discussions on Set operation variants, anyone?) as it could to any other function with mutable and immutable variants.
* It’s readily typeable on most keyboards (US and non-US, Mac and non-Mac), when even very simple automatic text replacement is available. (Set “!?” to be replaced with “‽” – done.)
* The language grammar change is very minor in scope. It’s unlikely that anyone has adopted the interrobang as a custom operator for any large amounts of code (and even if they had, there are multiple alternative sigils in the operator characters that could serve as a replacement.)
* If the restriction on postfix operators and “?” and “!” was relaxed slightly, Swift could even consider both “!?” and “‽” as synonyms in the lexer (I have no idea of the Real World Implications of this though…)
My initial thoughts were leaning towards the double exclamation “‼” – I’m only slightly on the side of the interrobang:
* the double exclamation is a shorthand for “double factorial” in mathematical notation, but
* distinguishing “‼” from “!” is easier IMHO than distinguishing “‽” from “?”.
It’s definitely an alternative sigil for consideration.
I’m wary of posing this idea on swift-evolution due to the monstrous amount of bikeshedding and potential centithreads that I don’t have time to read as it is. But folks following Erica might be a little more discerning and able to point out whether this is a completely hare-brained idea or actually has some merit 🙂
Note: WordPress seems to have replaced the “double exclamation” with the Emoji version of “double exclamation”. That wasn’t my intent.
[…] SE-0059: Update API Naming Guidelines and Rewrite Set APIs Accordingly (See also: Stop the Madness and fix the Swift API guidelines […]