Готовый перевод The Swift Programming Language (Swift 4) / Swift 4: API Design Guidelines

Основы

Понятность кода является самой важной вашей целью. Методы и свойства объявляются всего один раз, а используются очень часто. Разрабатывайте API так, чтобы сделать их использование понятным и лаконичным. При разработке прочтение объявления редко является достаточным; всегда проверяйте насколько понятно все выглядит в контексте.

Понятность кода намного важнее краткости. Несмотря на то, что Swift может быть очень компактным, нет задачи создать код с минимально возможным количеством символов. Краткость в Swift, это побочный эффект, получаемый из-за строгой типизации и свойств языка, которые естественным образом уменьшают объем кода.

Документируйте через комментарии каждое объявление. Пересмотр кода, осуществляемый во время написания документации, может оказать сильное влияние на качество вашего кода, поэтому не пренебрегайте этим.

Если вы затрудняетесь описать API простыми словами, возможно, вы спроектировали плохой API.

Используйте разновидность разметки, принятую в Swift:
https://developer.apple.com/library/prerelease/mac/documentation/Xcode/Reference/xcode_markup_formatting_ref/

Внимание! Этот перевод, возможно, ещё не готов.
Его статус: идёт перевод

Переведено на Нотабеноиде
http://notabenoid.org/book/70130/376414

Переводчики: trambalda