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