[swift-evolution] [Review] SE-0023 API Design Guidelines (when to use properties)

[Dave Abrahams]

on Sat Jan 23 2016, Jacob Bandes-Storch <swift-evolution at swift.org> wrote:

> Proposal link:
> https://github.com/apple/swift-evolution/blob/master/proposals/0023-api-guidelines.md
>
>> What is your evaluation of the proposal?
>
> I think there are more things which would make a "guidelines" document
> even
> better for promoting consistent code:
>
> - When to use functions vs. properties for getters. The changes in
> SE-0006
> <https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md>
> include
> "func min()" and "var underestimatedCount". SE-0005
> <https://github.com/apple/swift-evolution/blob/master/proposals/0005-objective-c-name-translation.md>
> includes "class func darkGray()". I imagine it should be implied that
> properties are more efficient to compute, but this doesn't seem to be
> applied consistently.

I'm glad you mentioned this, Jacob.  We had extensive internal
discussions about properties, and made substantial progress, but we do
not yet have wording suitable for the guidelines.  Let me tell you where
things stand.

,----[ Side Note, since you mentioned efficiency ]
| I originally wanted to uphold the principle that, “if it isn't O(1), you
| don't make it a property.”  The implication is that on collections,
| “count” would be a method.  That would include Array, for which counting
| the elements *is* O(1).  Some people argued that:
| 
| 1. The idea of writing “a.count()” instead of “a.count” to count the
|    elements of an Array was absurd.
| 2. Programmers don't draw conclusions about efficiency based on whether
|    something is a property.
| 3. The fact that Array would have an O(1) non-property that *could* have
|    been a property (if it weren't for CollectionType conformance)
|    undermines any communicative power that you might get from using this
|    distinction to choose properties.
| 
| I did not win that argument :-)
`----

So we surveyed the entire standard library, trying to arrive at some
consensus about what ought to be a property and what ought not to be
one.  Fortunately I happen to already have a write-up of those results:
https://gist.github.com/dabrahams/b6b79f19c2bf9b2a0083

The parts I'm not currently satisfied with are:

1. I don't know how to nail down what was meant by “intrinsic” in:

     Things that are “intrinsic” to the receiver are properties

2. (possibly-related): The following don't seem (to me) to be a clear
   fit for any of the criteria.  I think we made the right decision in
   most cases, but I don't know how to describe why:

   * description, debugDescription, customReflectable.customMirror
   * first
   * unsafePointer.pointee
   * string.utf8.nulTerminatedUTF8
   * collection.min()
   * sequence.iterator()

3. I don't understand the rationale we currently have for
   sequence.iterator() not being a property, even though I think that's
   the right choice.

I *do* think there's enough here to eventually turn it into wording for
the guidelines, but it's going to take a little more work.  If the
community can help us clarify the points above, I'm sure it could be a
big help!

Cheers,

-- 
-Dave