Комментарии и автоформат: Ctrl+T спасает friendships

Друг прислал свой поливальник «глянуть одним глазом»: четыреста строк, отступы танцуют в трёх размерах, над каждой функцией — пустота, а пороги стоят голыми числами. Один глаз превратился в вечер: я угадывал, что делает фильтр датчика, где кончается режим ночи и почему задержка именно сто миллисекунд. Смысл скетча я в итоге нашёл, но цену выставили не в рублях, а в дружбе — той самой, про которую кричит заголовок: код читают чужие глаза, и нечитаемый код стоит денег всем, включая автора.

База про Ctrl+T и имена была в уроке про форматирование и стиль — отступы, camelCase, константы заглавными. Здесь второй этаж: подписи над функциями в формате doc-комментария, шапка скетча с датой последней правки и ритуал коммита до форматирования, который спасает историю правок от размытия. Без своих функций в скетче тема не живёт: подписывать нечего, когда всё в loop.

Ни одна из привычек ниже не требует железа и не тратит байты платы — это работа с текстом на компьютере. Зато каждая окупается на первом же «покажи код»: на форуме, в чате курса или полгода спустя перед собственным носом.

Отдельно про имя команды: автоформат в меню зовётся Auto Format, а Ctrl+T — сокращение, которое пережило три версии среды и дюжину редакторов. Привычка дешёвая, но въедливая: две недели целенаправленного «сохранил — отформатировал», и рука жмёт связку сама, как сама жмёт Ctrl+S. Дальше в уроке я считаю связку в пальцах и говорю про то, что живёт вокруг неё.

Обычный комментарий // отвечает на вопрос в одном месте кода; doc-комментарий в формате /** ... */ над функцией отвечает на вопросы ко всей функции разом: что принимает, что возвращает, в каких границах живут параметры и какая грабля подстерегает на краю диапазона. IDE 2 подхватывает такие подписи в подсказках: начинаете набирать имя функции — и висит ваш же текст с границами вместо пустого автодополнения.

Мой формат подписи — три-четыре строки, не роман: первая — что делает, одной фразой; вторая — параметры с границами; третья — что вернёт при вырожденном входе. Подпись живёт над функцией и умирает вместе с ней: правите логику — правите и подпись, иначе она хуже отсутствующей, потому что врёт с уверенным лицом.

Где подписи не нужны: в setup и loop, в функциях-однострочниках, в коде, который переезжает в библиотеку, — там комментарий становится дублем заголовочного файла. Каноничные образцы удобно подсматривать в примерах из менеджера библиотек: File → Examples показывает, как оформляют код авторы библиотек, и это готовый эталон в один клик.

Про язык подписей честный совет: пишите на том языке, на котором думаете. Английский в doc-комментариях красив на чужих скриншотах, а быстро читать через год вы будете родный; я один сезон писал по-английски, потом конвертировал полсотни подписей обратно и больше не экспериментировал. Кириллица в комментариях IDE 2 показывается без кракозябр — беда была только у классики на части систем.

Шапка скетча — четыре строки в самом верху файла: имя проекта, что делает, дата первой версии и дата последней правки. Через полгода именно последняя правка отвечает на главный вопрос «свежий ли это файл»: у меня в папке лежат близнецы poliv_v1.ino и poliv_v2.ino, и только шапка рассказывает, что v1 — с ручным запуском, а v2 — финал с кнопкой. Дата создания не говорит почти ничего, дата правки — всё.

Второй слой шапки — предположения, на которых держится код: «порог 405 — калибровка этого конкретного датчика», «работает с прошивкой 1.4, выше падает». Это те самые комментарии «почему» из урока про стиль, но в формате учётной записи: условия и версии переписываются при каждой смене. Бэкап в git снимает половину нагрузки с шапки — история там честнее, — но коммит не объясняет, почему выбран порог, а четыре строки сверху объясняют.

Против перегруза: шапка — не дневник. Записей «добавил пробел, поправил отступ» в ней быть не должно; это место для предположений, без которых код непонятен, и для дат, без которых непонятен файл. Захотелось вести дневник — есть git, он делает это лучше шапки на порядки.

Где шапка работает в обе стороны: скетч выложен на форум — отвечающие видят версию и дату и не спрашивают, какая у вас прошивка; скетч вернулся из бэкапа — по датам видно, какой из трёх близнецов новее, без открытия каждого. Дешёвая метка времени бьёт любые имена вида final_final_2 — эта эпидемия живёт в папках у всех, и шапка лечит её без переименований.

Мнение, к которому я пришёл через дюжину чужих скетчей: единый стиль важнее красивого. Соглашение «отступы как получится, имена как удобнее» в одном файле читается хуже, чем скучная, но ровная разметка; зато микс из идеального файла и хаотичного в одном проекте читается хуже всего — глаз каждый раз перенастраивается. Поэтому спор «табы против пробелов» я закрыл в пользу «что-то одно на весь проект», и это решение дешёвое: Ctrl+T делает его за две секунды во всех вкладках.

Красота при этом — отдельная дисциплина: вычурные макросы, цепочки тернарников в одну строку, хитрые типы там, где хватает индекса. В скетче на плату «красивое» чаще всего означает «меньше строк», а не «понятнее» — а это противоположные цели, когда код через полгода читать вам же. Условие для несогласных: если скетч живёт один вечер и в плату больше не вернётся, игнорируйте всё написанное выше — там нечему ломаться.

Практический минимум, который я требую от собственных скетчей: автоформат во всех вкладках, doc-подписи над тремя-пятью главными функциями, шапка с датой правки и пороги с условиями. Это тридцать минут на проект с запасом. Всё прочее — по желанию: если у проекта появляется второй читатель, дополняйте, а до того момента ровный формат и подписи закрывают большую часть вопросов.

Спор о стиле я переношу в плоскость автоматизации: всё спорное решается кнопкой, а не совещанием. Формат закрывает Ctrl+T, потому что выбор правил вообще не у нас; имена закрывает схема из урока про стиль; подписи — шаблон из четырёх строк. Остаётся спорить о порогах и логике — то есть о деле, ради которого скетч и пишется.

Наводить порядок в чужом или полугодовалом скетче приучился по трёхшаговому маршруту. Шаг первый — Ctrl+T по всем вкладкам и коммит «только формат»: разница перестаёт шуметь, и дальше видно каждую настоящую строку. Шаг второй — переименование худших имён: t3 и x2 умирают, на их место приходят urovenPochvy и periodPoliva. Шаг третий — doc-подписи над главными функциями и шапка с датами. После третьего шага скетч читается вслух, и вопросы собеседника кончаются.

Тест на готовность простой: отправьте скетч тому, кто его не видел, вместе с одним сообщением «что тут сломано» — и если ответы приходят по существу, а не «не понял, где что», подписи сработали. Дружба с тем, кто просил посмотреть код, восстанавливается по цене вечера, а не недели: Ctrl+T и четыре строки шапки вычёркивают половину пояснительных сообщений.

Пара слов о технике: переключение вкладок, Ctrl+T и Ctrl+Z живут рядом с прочими клавиатурными ходами, которые разобрали в уроке про горячие клавиши IDE. Автоформат, разогнанный до привычки, не съедает время, а отдаёт его: две секунды в конце правки против минут расшифровки на следующей сессии. Итог главы один: код пишется для глаз, и своих, и чужих, — порядок в тексте дешевле любых других инструментов.