Swift API Design Guidelines

Reference: swift.org/documentation/api-design-guidelines.

The test for every rule below is the same: read the call site, not the declaration. A name is declared once and used many times, so an awkward declaration that reads fine at the use site beats a tidy declaration that reads badly there. When in doubt, write the call site out and read it as an English phrase.

Fundamentals

• Clarity at the point of use outranks brevity. Swift's terseness should come from the type system and inference, not from cutting words a reader needs.
• Every public declaration gets a documentation comment (see the swift-docc skill for the format and building the catalog). If the summary is hard to write in one sentence fragment, the API is probably shaped wrong — fix the design before you fix the doc comment.

Promote Clear Usage