Если вы разрабатываете приложения на Swift, в том числе и приложения, связанные с выполнением Заданий стэнфордского курса, вам необходимо знать принципы проектирования API в Swift, которые отличаются от принципов проектирования API в Objective-C и других языках.  И это зафиксировано в руководстве по проектированию Swift API «API Design Guidelines«, выпущенному Apple. Кулиничев Евгений  любезно предоставил перевод этого руководства на русский язык для размещения на этом сайте. Вы можете посмотреть его в Google Doc  или  скачать в PDF формате для изучения в offline:

Swift API design guidelines.pdf

Но прежде, чем вы приступите к его изучению, необходимо дать вам некоторые фундаментальные идеи, которые были заложены в этот документ:

• Обеспечение понятности кода в точке его использования
• Понятность кода более важна, чем его краткость
• Создание самодокументируемого API

Код пишется один раз, а читается многократно. Очень важно, чтобы Swift код был читаемым и понятным в точке использования. Хотя кажется, что это очень знакомое требование, оно отличается от правил проектирования API в Objective-C. В Swift мы не хотим унаследовать многословный стиль Objective-C, в котором вся необходимая информация передается через хорошо сконструированный API, и редко бывает хорошо читабельной в точке использования. В Swift недостаточно, чтобы API был хорошо читабельным в точке определения; он должен быть читабельным и иметь смысл в различных точках применения. И вы увидите в руководстве, как это достигается.

В то же время мы не хотим качнуть маятник в противоположную сторону. Swift код является более компактным по сравнению с кодом Objective-C, но это не является целью проектирования API. Понятность кода более важна, чем его краткость. При конструировании API, наш код естественно будет более компактным благодаря определенным возможностям самого языка Swift, но мы не должны явно ставить это целью при проектировании API.

В связи с поставленными целями, дается ряд практических рекомендаций по наименованию методов, функций, их аргументов, свойств,  переменных и associated types:

1. Избавьтесь от избыточных и неинформативных слов в названиях
2. Методы и функции лучше всего именовать глаголом
3. Типы и имена свойств, варианты enums, имена функций и их параметров и даже локальные переменные внутри тела функции должны описывать их роль, а не тип.
4. Существительные в большинстве случаев подходят для возвращаемых значений
5. Имена функций вместе с параметрами должны читаться как осмысленное и грамматически правильное предложение на английском языке.
6. Используйте «ed» or «ing» для не изменяющих (non-mutating) методов и основной глагол в повелительной форме для изменяющих (mutating) методов. Например, sort — это изменяющий метод, но sorted и trimmingCharacters —  оба не изменяющие.

Это лишь самые общие правила, из которых, конечно, есть исключения. Все они с примерами подробно представлены в «Руководстве по проектированию Swift API«. Примеры его использования вы можете посмотреть также в стандартной библиотеке, все функции которой спроектированы с учетом этого руководства,