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

[Dave Abrahams]

on Fri Jan 22 2016, Kevin Lundberg <swift-evolution at swift.org> wrote:

>> *Protocols* that describe what something *is* should read as nouns
> (e.g. |Collection|). Protocols that describe a *capability* should be
> named using the suffixes |able|, |ible|, or |ing| (e.g. |Equatable|,
> |ProgressReporting|).
>
> I personally like the idea behind the current convention for protocols
> that describe a thing (IntegerType, CollectionType, etc) where there is
> a suffix of Type appended to the end, so I give this specific part of
> the proposal a -1. 

For some people, that convention made no sense at all, no matter how
many times I explained the rationale: they would always come back to,
“but that's a protocol, not a type, so ending its name with Type makes
no sense.”  At some point, empirical evidence of people's cognitive
dissonance outweighs nice theories, and I had to admit that it wasn't
working for people overall.

(That assessment was from a small sample, and if nobody in the community
feels the same way, that would be significant news.)

> The specific wording of the protocol's name is not so important as the
> recognition at a glance that this is a protocol vs a concrete type. I
> like being able to infer at a glance how I'm expected to use a
> specific type reference based on its name alone; otherwise I may have
> to refer back to the type definition to refresh my memory of whether
> or not it is in fact a protocol or is something else.

That was part of the original motivation.  One issue with that is that
protocols without Self requirements or associated types *are* concrete
types, so it weakens the argument for making a strong distinction.

The other thing, is, I wonder how much of that warm fuzzy feeling we get
from being able to know at a glance it's a protocol is actually useful
in programming or maintenance.  After we made the changes in the
standard library I was quite pleased by what IMO was the resulting
improvement in readability.  I ask that you take a look at the effect
this has on actual code.

>From the standard library,
https://github.com/apple/swift/compare/swift-3-api-guidelines has a few
of these.  You might try this on your own project.

> This change could also lead to confusion among some developers. For
> someone who is new to Swift, would they know they should use Bool over
> Boolean if they've seen both types before? Both names look reasonable to
> store a boolean value, but the semantics of each type differ
> significantly. 

Well, yeah.  BooleanType should be retired; if we didn't know that was
in the plan, we'd have renamed it to BooleanProtocol or TruthValue or
somthing.

> Someone may try to have a type conform to Bool instead of Boolean,
> which would obviously not work, but could cause some consternation for
> developers who don't know the difference by heart.  Naming the
> protocol BooleanType at least calls out that this may not be
> conceptually the same as a plain boolean value, which could make a
> developer think twice before trying to use that over Bool.
>
> Removing some common prefix 

suffix?

> from these kinds of protocols could also run the risk of
> unintentionally shadowing type names, if someone wanted to write their
> own Collection or Error struct or class for instance, or if a
> pre-existing concrete type in their code turned out to unexpectedly
> shadow a protocol in a new dependency that they want to add. These
> situations would not cause any technical hiccups due to module
> namespacing, but it could lead to confusion when a developer forgets
> to qualify the name and tries to use one type where the other is
> expected.

Yes, but shadowing surprises are a fact of life whether we make this
change or not.

> In short, appending Type (or something like it) i think is a reasonable
> convention to keep around for non-behavioral protocols.
>
> As far as alternatives to 'Type', I personally don't like the suffix
> 'Protocol' as much (which is suggested as a disambiguation option in the
> related standard library review), since 'Type' is shorter, feels nicer
> to read, and describes the purpose of the protocol well to me. C#'s
> approach of prefixing all interfaces with a capital I would be even more
> succinct, but I personally don't think that approach would look nice to
> read either. (PCollection, PBoolean? Ick.)

Ick indeed.

-- 
-Dave