[swift-evolution] [Accepted with modifications] SE-0023 API Design Guidelines

[Douglas Gregor]

The review of SE-0023 "API Design Guidelines" ran from January 22...February 5, 2016, with the discussion continuing long afterward. We were thrilled with the scope and depth of the community response to this proposal. The proposal is accepted with some significant modifications, detailed below. The resulting API Design Guidelines are on swift.org at https://swift.org/documentation/api-design-guidelines/

The most significant modification to the proposed guidelines is an expansion in the use of first argument labels. For example, while the originally proposed rules put most descriptions of the first argument in the base name, e.g.,

  x.moveFrom(x, to: y)           // bad: doesn't follow guidelines
  x.removeBoxesHavingLength(12)  // bad: doesn't follow guidelines

The accepted rules use argument labels instead:

  x.move(from: x, to: y)
  x.removeBoxes(havingLength: 12)

The specific, accepted rules for argument labels are available at https://swift.org/documentation/api-design-guidelines/#argument-labels

Replaced the "Be Grammatical" section with a clearer discussion about striving for fluent usage, specifically providing guidelines for naming initializer and factory methods and naming functions according to their side effects.

Enum cases are now lowerCamelCase, like all other non-types in the 
language, e.g.,

  enum Optional<Wrapped> {
    case none
    case some(Wrapped)
  }

Initialisms at the beginning of a non-type name are now lowerCamelCased, e.g.,

  let htmlElement = HTMLElement()

Introduced a guideline to name closure parameters and tuple members where they appear in your API.

Numerous clarifications throughout, including improvements to the discussion of using argument labels to clarify the roles of parameters, choosing parameter names to clarify documentation, clarifications to the "-ed/-ing" rule, and so on.

Thank you!
Doug Gregor
Review Manager