Комментарий
комментарий в коде
Это понятие впервые встречается на программе «Электроника, программирование и инженерная практика» — примерно 13-14 лет (7-8 класс).
Заметка для людей внутри кода: исполнитель её полностью пропускает. В ней объясняют, зачем нужен этот кусок программы.
Пометки карандашом на полях книги: текст книги они не меняют, а понять его помогают.
Найти в скетче Arduino строки после «//», временно удалить их и убедиться, что программа мигает светодиодом как раньше.
Текст в коде, который исполнитель не читает: в скетчах Arduino — всё после // до конца строки. Пишут для людей, в том числе для себя через месяц: объясняют замысел («зачем»), а не пересказывают команду («что»). Комментарием также временно отключают строку кода — удобно при отладке.
Заменить бесполезный комментарий «// увеличиваем x на 1» на полезный, объясняющий зачем; закомментировать строку delay(1000) и предсказать поведение скетча до запуска.
Фрагменты исходника, отбрасываемые при трансляции: однострочные (// в C++, # в Python) и блочные (/* … */). Хороший комментарий фиксирует намерение и неочевидные решения; устаревший — вреднее отсутствующего, потому что врёт. Особый случай — docstring в Python: это не комментарий, а строка документации; она сохраняется в программе, и по ней help() показывает справку. Краевой случай: «мёртвый» закомментированный код копится и мешает чтению — его удаляют, историю хранит система контроля версий.
Добавить к чужой функции на Python docstring и вызвать help(); найти и убрать один комментарий, который пересказывает код, и один устаревший, который врёт.
Частое заблуждение
«Комментарии нужны компьютеру, чтобы лучше понять программу». Нет: исполнитель пропускает их целиком; комментарии пишут для людей — в том числе для себя через месяц.