// Не запускайте эту строку!
Смотрите, документация и комментирование кода крайне важно. Вы должны это делать. Вы должны сделать это сейчас.
Не знаете как? Прочтите и узнайте об однострочных комментариях, многострочных комментариях, вложенных комментариях и о том, как комментарии могут помочь вам, когда вы выбираете свою функцию.
Сложность: Начинающий | Легко | Нормальный | Испытывающий
Предпосылки:
- Уметь создать Hello, World! Приложение для iOS (руководство ЗДЕСЬ)
OR
- Используйте Swift Playgrounds, чтобы ввести код (руководство ЗДЕСЬ)
Терминология
Комментарии: способ включения текста в ваш код, который не будет выполняться компилятором.
Компилятор: программа, которая преобразует инструкции в машинный код или форму более низкого уровня, чтобы они могли быть прочитаны и выполнены компьютером.
Документация: текст (или диаграммы) для описания компьютерного кода.
Косая черта: символ /.
Функция: группа операторов, которые вместе могут выполнять функцию.
Вы ДОЛЖНЫ писать код, который не выполняется ... WHAAA
Вам может быть интересно, зачем вам вообще включать текст, который не запускается как код.
Причина на самом деле довольно проста. Код предназначен для компьютеров и часто ценится за краткость, удобство обслуживания и простоту. Теперь я упустил еще одно преимущество хорошо написанного кода, а именно самодокументирующийся код.
Самодокументирующийся код - это код, который понятен и понятен людям.
Это означает, что ваш код должен быть идеальным во многих отношениях.
Вы видите здесь возможную проблему?
да. Ты не идеален. Вы ... не идеальны. Вы делаете ошибки, и сложно сделать все идеально.
Таким образом, ваш код может быть не совсем логичным для читателя вашего кода. Это может быть даже потому, что то, что вы хотите, чтобы iOS делала, довольно сложно и сложно (бизнес-логика иногда может быть сложной, а иногда это не является чьей-либо ошибкой).
Чтобы помочь людям читать ваш код, вы можете добавить documentation. iOS не заинтересуется вашими забавными / полезными размышлениями, но ваши коллеги, безусловно, будут не только заинтересованы, но и благодарны за вашу помощь и заботу, которую вы предприняли, чтобы сделать свой код интересным для понимания!
Основные комментарии
Здесь не должно быть проблем. Swift знает, что нужно игнорировать строки, которые начинаются двумя косыми чертами, то есть строка является comment, если перед ней стоит //.
Таким образом, следующее абсолютно ничего не будет делать. Теперь имейте в виду, что если вы обычно набираете какой-нибудь нормальный читабельный текст, Swift compiler выдаст довольно неприятную ошибку:
// This is ignored
это работает даже с кодом, который обычно выполняется. Таким образом, оператор print больше не будет выполняться
// print ("This will never print")
потому что это выполняется секретным кодом - двойная косая черта // делает эту строку comment.
Многострочные комментарии
Если у вас есть много комментариев, чтобы сделать что-то особенно ясным для человека, Swift вы это сделали. Ну, конечно, вы можете продолжить несколько строк с помощью двойной обратной косой черты, я ценю это. Однако проще иметь один начальный символ для комментария и один символ для конца комментария.
Начало комментария: /*
Конец комментария: */
Это означает, что вы можете написать множество вещей между этими двумя символами и быть очень довольны этим.
/*
This is an example of a multiline comment
so the next print statement will not actually print anything
print ("will not print")
*/
Вложенные многострочные комментарии
Зачем вам это нужно? Вероятно, вы будете копировать и вставлять элементы в свой код и помещать комментарий в комментарий.
Кто не хотел бы, чтобы их жизнь была проще?
/*
This is an example of a multiline comment
so the next print statement will not actually print anything
print ("will not print")
/*
This beautiful comment is within the other one, which is just above it.
Ok?
*/
*/
Комментируя ваш код
Option-Command- / - это ярлык для commenting нирваны.
Вам нужно выбрать свойство (идеальное начало строки), а затем нажать Option-Command- /, чтобы добавить довольно привлекательный комментарий (этот конкретный комментарий имеет /// в начале).
То же самое можно сделать и с функциями. Итак, если у нас есть простая функция, она добавит /// в начале, когда мы тоже нажмем Option-Command.
Теперь есть более интересный тип функций. В следующем примере есть как входные параметры, так и выходные параметры.
func takeInputProcessToOutput(input: String) -> String {
return "This is the output: " + input
}
Теперь нам нужно описать входные и выходные параметры функции. Это поможет будущим программистам (или себе в будущем, потому что вы собираетесь забыть, помните!) Знать, как используется функция и даже что она делает (хотя технически ваше имя функции должно прояснить это).
А теперь самое лучшее. Вы можете узнать информацию о любой функции с помощью Swift compiler, нажав опцию на клавиатуре и одновременно нажав function. Когда вы это сделаете, вы получите информацию о function (на самом деле комментарии, которые написаны выше).
Комментирование кода - некоторые правила
- Когда вы используете комментарии, убедитесь, что каждый комментарий настолько сложен, насколько он должен быть - простота является ключевым моментом. Вы пытаетесь упростить задачу
- При необходимости используйте многострочные комментарии
- Используйте комментарии, но не злоупотребляйте ими. Не пишите ненужные комментарии.
- Используйте комментарии в той же строке, что и активный код
- Не дублируйте код в своих комментариях. В комментариях указывается, почему код работает; хорошо написанный код должен описывать как
- Комментируйте код, даже если вы разработчик-одиночка. Относитесь к себе как к коллеге, что имеет большой смысл, поскольку в будущем вы ничего не вспомните сейчас.
Расширьте свои знания
- У Apple есть хороший документ о комментариях (ЗДЕСЬ)
Контактное лицо в Twitter:
Любые вопросы? Вы можете связаться со мной здесь
