[swift-evolution] [swift-evolution-announce] [Review] SE-0023 API Design Guidelines

[Gwendal Roué]

>> Hi Dave,
>> 
>> Let me add the following to my ideas on union().  I actually reviewed
>> SetAlgebra quickly and I think it could conform to the guidelines
>> better if it used the following:
>> 
>> // Non-mutable methods
>> let union = a.adding(b)				// returns a ∪ c
>> let intersection = a.intersecting(b)		// returns a ∩ c
>> let difference = a.subtracting(b)		// returns a - b
>> let xor = a.xoring(b) // returns a △ b (a.k.a. "symmetric difference"
>> or "exclusive or")
>> 
>> // Mutable methods (in-place)
>> a.add(b)
>> a.intersect(b)
>> a.subtract(b)
>> a.xor(b)
> 
> OK.  You may think this is just me, but a set abstraction that doesn't
> include an operation called "union" is really hard for me to accept.
> It's a basic part of the set abstraction.

I’m sorry but why do we let specific domains interfere with the effort to write general guidelines? Guidelines are not laws, and nobody will be punished by escaping them when context and good taste require it!

The "Use Terminology Well" section of https://swift.org/documentation/api-design-guidelines/#use-terminology-well should well accepted by all as the rule 0, don’t you all think?

Guidelines are there to help people naming stuff. Exhibiting countless exceptions is both easy and void.

Consider Cocoa, whose naming guidelines are still shining. It’s full of exceptions. The infamous -[CLLocation getDistanceFrom:] is well known. But there are countless other exceptions which fall under the radar of most people. The oddity of NSMutableSet. NSMakeRange which must not be that much infuriating, since it has not been deprecated yet.

Gwendal