The inPlace proposal is excellent. As suggested something like x.=f() would be perfect to distinguish mutating methods .Something I don't like from the API design guidelines is that non mutating methods like enumerate would be become enumerated. In my mind enumerate is a word of art and I don't ever think of it as muting so having to always use enumerated in the future seems weird. Also having to ed/ing non mutating methods seems to make mutating methods more important. <div><br><div>//non mutating suggestion</div><div>x.sort()</div>x.split()<br><div><br></div><div>//other ideas for mutating methods names</div><div>x.sort*()</div><div>x.sort&() // I like & the most</div>x.split&()<br><div>x.sort@()<br><div><br></div>By marking a method with a special character at the end, the reader would know that the method mutates. <br><div><div><div><br>On Saturday, January 23, 2016, Dave Abrahams via swift-evolution <<a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a>> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><br>
on Fri Jan 22 2016, David Owens II <<a href="javascript:;" onclick="_e(event, 'cvml', 'swift-evolution@swift.org')">swift-evolution@swift.org</a>> wrote:<br>
<br>
>> Compensate For Weak Type Information as needed to clarify a parameter’s role.<br>
>><br>
>> Especially when a parameter type is NSObject, Any, AnyObject, or a<br>
>> fundamental type such Int or String, type information and context at<br>
>> the point of use may not fully convey intent. In this example, the<br>
>> declaration may be clear, but the use site is vague:<br>
>><br>
>> func add(observer: NSObject, for keyPath: String)<br>
>> grid.add(self, for: graphics) // vague<br>
>><br>
>> To restore clarity, precede each weakly-typed parameter with a noun describing its role:<br>
>><br>
>> func addObserver(_ observer: NSObject, forKeyPath path: String)<br>
>> grid.addObserver(self, forKeyPath: graphics) // clear<br>
><br>
> I don’t understand why to compensate for weak type information we put<br>
> some of that compensation in the name of the function and other parts<br>
> of it in the [external] name of the parameter.<br>
<br>
IIUC, some people feel strongly that it would be really strange and<br>
nonuniform to have a substantial fraction of methods with an argument<br>
label on the first argument unless that percentage was nearly 100.<br>
<br>
[I don't know whether there's an "official terminology" for these names,<br>
but we've been calling them "argument labels" in the naming discussions.<br>
Note that the ("internal") parameter names aren't strictly internal as<br>
they get used in documentation comments, and should be chosen<br>
accordingly. So, I'm using the terms "argument label" and "parameter<br>
name".]<br>
<br>
> If we were going to reference functions like this:<br>
> addObserver:forKeyPath, then I can understand it. But that’s not the<br>
> plan of record, it’s to do this: addObserver(_:forKeyPath).<br>
<br>
That's an interesting argument.<br>
<br>
> Regardless of the default naming scheme, it seems like the rule should<br>
> be to use external names to clarify that parameters role.<br>
><br>
> func add(observer observer: NSObject, forKeyPath path: String)<br>
> grid.add(observer: self, forKeyPath: graphics)<br>
><br>
> This promotes a very clear and consistent rule: weak type information<br>
> should be clarified by the parameter’s external name. There are no<br>
> exceptions for the first parameter.<br>
<br>
That seems very clean to me.<br>
<br>
> Otherwise, it seems like there is super fine line between this rule<br>
> and the next one below.<br>
><br>
> Additionally, this also alleviates my concerns with the default<br>
> parameter have _ as the external name by default because this<br>
> addresses the case when it would be desirable to have that<br>
> name.<br>
<br>
Sorry, I don't understand what you're getting at here.<br>
<br>
> Further, the case below handles the case when it’s not.<br>
><br>
>> Omit Needless Words. Every word in a name should convey salient information at the use site.<br>
>><br>
>> More words may be needed to clarify intent or disambiguate meaning,<br>
>> but those that are redundant with information the reader already<br>
>> possesses should be omitted. In particular, omit words that merely<br>
>> repeat type information:<br>
>><br>
>> public mutating func removeElement(member: Element) -> Element?<br>
>> allViews.removeElement(cancelButton)<br>
>><br>
>> In this case, the word Element adds nothing salient at the call site. This API would be better:<br>
>><br>
>> public mutating func remove(member: Element) -> Element?<br>
>> allViews.remove(cancelButton) // clearer<br>
>><br>
>> Occasionally, repeating type information is necessary to avoid<br>
>> ambiguity, but in general it is better to use a word that describes<br>
>> a parameter’s role rather than its type. See the next item for<br>
>> details.<br>
><br>
> The description here seems to overlap with the “Compensate for Weak<br>
> Type Information” rule, especially with the clause: “repeating type<br>
> information”. It may be better to re-work the example to be<br>
> `removeItem(member: Element)` to make this distinction more clear that<br>
> it’s not type information being removed.<br>
<br>
Oh, great point!<br>
<br>
> Also, by clarifying that statement, the above rule change I suggested<br>
> would be consistent. Type information clarification goes into the<br>
> external parameter name, functionality clarification goes into the<br>
> function name. Those are hard-n-fast rules that are straight-forward.<br>
<br>
I like 'em, FWIW.<br>
<br>
>> Be Grammatical<br>
>><br>
>> When a mutating method is described by a verb, name its non-mutating<br>
>> counterpart according to the “ed/ing” rule, e.g. the non-mutating<br>
>> versions of x.sort() and x.append(y) are x.sorted() and<br>
>> x.appending(y).<br>
><br>
> Is this guideline suggesting that we should design our APIs to<br>
> generally have both mutating and non-mutaging counterparts?<br>
<br>
Definitely not.<br>
<br>
> As other have pointed out, this is also very hard to do all the<br>
> time. I think the alternatives are worse.<br>
<br>
The alternatives to always creating mutating/nonmutating pairs? What<br>
alternatives have you considered, and what do you see the consequences<br>
to be?<br>
<br>
> It would be nice if there were a way to annotate all member functions<br>
> as mutating/non-mutating to really by-pass this ambiguity.<br>
<br>
I don't know what you mean by that. Can you explain?<br>
<br>
FWIW, there are potential language-level approaches to this problem<br>
(e.g. <a href="https://github.com/apple/swift/blob/master/docs/proposals/Inplace.rst" target="_blank">https://github.com/apple/swift/blob/master/docs/proposals/Inplace.rst</a>),<br>
but in the absence of language features, it's something we need a<br>
convention for.<br>
<br>
--<br>
-Dave<br>
<br>
_______________________________________________<br>
swift-evolution mailing list<br>
<a href="javascript:;" onclick="_e(event, 'cvml', 'swift-evolution@swift.org')">swift-evolution@swift.org</a><br>
<a href="https://lists.swift.org/mailman/listinfo/swift-evolution" target="_blank">https://lists.swift.org/mailman/listinfo/swift-evolution</a><br>
</blockquote></div></div></div></div></div>