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

[Patrick Gili]

>> - Under "Fundamentals", there is a bullet called "Write a
>> documentation comment...". Under this bullet, this is another bullet
>> called "Use a single sentence fragment...". Why? 
> 
> Because it leads to a concise, readable summary that works well with
> tools and often fully describes the API.  It is also easy to do.  It's
> crucial that the most important part of the documentation is also easy
> to produce, or people won't do it.
> 
>> I find sentence fragments often detract from clarity and concise
>> nature, which can lead to confusion.
> 
> We have lots of examples that follow this style in the Swift standard
> library.  Can you point at some that are confusing, unclear, or not
> concise because they use sentence fragments?
> 

In a previous email, Erica explained well the intent of the guideline by expanding on it, providing a good example and a good "anti-example". I also spent some quality time with the standard library source and think I understand the intent: eliminating redundancy in the interest of maintaining focus.

>> - Under "Naming", there is a bullet called "Compensate for Weak Type
>> Information...". The example provided is confusing. First, it
>> contradicts the guidance relating to omitting needless words. It
>> suggests that
>> 
>> func add(observer: NSObject, for keyPath: String)
>> 
>> becomes
>> 
>> func addObserver(_ observer: NSObject, forKeyPath: String)
>> 
>> This results in "Observer" followed by "observer". Why is this more
>> clear?
> 
> Because it's not the declaration site that matters; it's the use site.
> 
> Just to take the first use-site I could find with GitHub search, imagine
> the code at
> https://github.com/phileggel/Hangman/blob/c14fbbfd06e58527832c0634785aee45cb9e5e13/SwiftHangman/View%20Controllers/HMViewController.swift#L11 <https://github.com/phileggel/Hangman/blob/c14fbbfd06e58527832c0634785aee45cb9e5e13/SwiftHangman/View%20Controllers/HMViewController.swift#L11>
> said "add" instead of "addObserver".  Would it make sense?

These terms, "declaration site" and "use site" are new to me. Could you please provide a brief explanation?

Nevertheless, the code that you have reference clarifies the point.

>> - Under "Naming", there is a bullet called "Uses of non-mutating
>> methods should read as noun phrases...". This bullet provides an
>> example of an exception. Why would calling this method firstAndLast()
>> have less clarity than split()? 
> 
> Because, among other things, "firstAndLast" incorrectly implies you only
> get two parts back.

My misunderstanding. I now see you were referring to String.split().

> 
>> Perhaps a better example is in order.
> 
> Suggestions welcomed.

The example is fine, but confusing because it taken out-of-context. Maybe expand the example to read more like this:

let fullName = "Johnny Appleseed"
let firstAndLast = fullName.split()

>> - Under "Naming", there is a bullet called "When a mutating method is
>> described by a very, name its non-mutating counterpart...". On the
>> surface this appears to provide good guidance, I think in practice it
>> becomes difficult and doesn't necessarily provide the desired
>> result. I think Ruby provides a better example of how the desired
>> result is very clear. In Ruby, the name of a mutating method is
>> designated by an exclamation point at the end of the name. 
> 
> Yes, but we don't have the necessary language features
> (e.g. https://github.com/apple/swift/blob/master/docs/proposals/Inplace.rst <https://github.com/apple/swift/blob/master/docs/proposals/Inplace.rst>)
> to do something like that today, so we need to use a naming convention
> instead.

I like this proposal. However, it sounds like this is something that won't be in Swift 3?

>> For example, myString.reverse() returns the value of the reversed
>> string, while myString.reverse!() mutates myString with the reversed
>> value. I'm not necessarily proposing that Swift use the exclamation
>> point for this purpose (as Swift already uses this force unwrapping),
>> so much as I'm proposing that you investigate how other languages
>> clearly disambiguate non-mutating and mutating methods.
>> 
>> - Under "Conventions", there is a bullet called "Methods can share a
>> base name when they share the same basic meaning...". There are some
>> examples when this convention does not apply. 
> 
> Example, please?  I have no idea what you might be referring to.
> 
>> I think it would be helpful to illustrate to the reader how to address
>> these exceptions (i.e., do this, instead of that).

My apologies, my thought was poorly expressed. Let me try again. The guideline provides some examples of when methods should not share a base name. For example,
extension Database {
  /// Rebuilds the database's search index
  func index() { ... }

  /// Returns the `n`th row in the given table.
  func index(n: Int, inTable: TableID) -> TableRow { ... }
}
A beginner is going to ask, "If this isn't what I'm supposed to do, then what is acceptable?" It might be useful to expand the guideline to help the beginner. This last example was somewhat obvious, but the next example is necessarily so obvious:
extension Box {
  /// Returns the `Int` stored in `self`, if any, and
  /// `nil` otherwise.
  func value() -> Int? { ... }

  /// Returns the `String` stored in `self`, if any, and
  /// `nil` otherwise.
  func value() -> String? { ... }
}
>> 
>> - Under "Conventions", there is a bullet called "Prefer to follow the
>> language's defaults for the presence of argument labels". Be aware
>> that the current compiler issues the warning when the first argument
>> label is "_", "Extraneous '_' in parameter: <parameter> has no keyword
>> argument name". I would either like the compiler to not issue a
>> warning for this use case, or at least give the developer the means to
>> disable this warning.
> 
> I understand.  I don't think your request will get the traction you'd
> like if you don't expose it somewhere other than in this thread.  We're
> not considering new language rules here.

Point taken.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160129/a31e6523/attachment-0001.html>