Приветствую всех программистов, а также сочувствующих. Кто из нас хотя бы раз в жизни не оставлял комментарии в коде? Был ли это ваш код, а может, чужой? Что за комментарии вы написали: полезные или не очень? А может, они были забавные, чтобы порадовать коллег или тимлида на следующем ревью? Давайте попробуем немного порассуждать и дать ответы на эти вопросы в формате небольшой заметки. Постараемся понять, что движет людьми, комментирующими свою программу. Упор сделаем на нестандартные, весёлые комментарии. У нас припасено для вас несколько отличных примеров. Поехали.  Все большие серьёзные исследования обычно начинаются с экскурса в историю. И чем глубже экскурс, тем лучше. Не буду отступать от традиций. Но сначала поговорим немного о предметной области – программировании и комментировании кода. Думаю, никто не будет оспаривать того факта, что программирование – занятие творческое. Сродни писательству, с примесью технологий и философии. Современная программа, по сути, "книга" с инструкциями для компилятора, или виртуальной машины и компилятора. Несколько упрощённо, но я хочу передать основную мысль: эту "книгу" с кодом читает не только машина, но и человек. При этом человек не только смотрит, но и правит код, на что требуется много времени и сил. Поэтому, несмотря на присутствующие элементы творчества, работа программиста всё же бывает довольно рутинна. Так что эмоциональная составляющая очень важна. Человек — существо социальное. А какое живое общение может быть с машиной? И как радостно бывает в процессе работы с кодом встретить послание самому себе с какими-то пояснениями или забавными комментариями. Ещё лучше, если послание оставил для вас другой разработчик. При этом он, возможно, и не рассчитывал, что оставляет комментарий именно для вас. Чувствуете драматизм? Вот вы уже и общаетесь. Часто — совершенно незнакомые люди. Но вот так, поплевав на ладони, взяли в руки воображаемые лопаты и как будто работаете сообща. Пробираетесь сквозь хитросплетения в коде и пытаетесь понять, как оно вообще работает. Оставляете друг другу подсказки и весёлые пасхалки. Сопричастность и командная работа в действии. Наконец, часто требуется просто выплеснуть накопившиеся эмоции. А если эти эмоции связаны с кодом, то комментарии как раз и позволяют запечатлеть что-то наподобие: Вернёмся к истории, желательно, древней, и не забудем про письменность. А что может быть древнее, чем слово? Ну, то самое, которое было в начале. Учёные, правда, утверждают, что была наскальная живопись. Это неосознанное желание даже древнего человека передать весточку собратьям или потомкам. Показать свой быт, обычаи, запечатлеть сцены охоты, праздников. Некий комментарий к своей повседневной и такой тяжёлой жизни. Да, делали как могли. Но ведь делали!  Дальше было разное. История развития письменности интересна и неоднозначна. По современным представлениям считается, что было несколько центров её зарождения. Более подробно про это можно почитать, например, в статье из Wikipedia. Но как бы там ни было, человечество проделало огромный путь от начертания простейших рисунков на глиняных табличках (Месопотамия) до современных цифровых методов генерации текста. В том числе, и текста комментариев в коде. Кстати, о технологиях: вот статья про историю развития компьютера из той же Wikipedia. Не благодарите. И вот он — XX век с его стремительным развитием техники. Первые механические, а затем и электронные вычислительные машины. Кстати, вы знали, что Mercedes делал в том числе и арифмометры? Я не знал.  Конечно, сначала с комментариями к программам было не очень. Не думаю, что про такое вообще думали. Долгое время для собственно программирования использовали перфокарты. Конечно, можно было прямо на них написать что-то весёлое, например: "Эй, ребята, посмотрите какой тут прикольный узор из дырочек". Но кто бы оценил?  Первые компьютеры были огромные, сложные и использовались для очень серьёзных вычислений. И программисты были под стать им.  Какие уж тут весёлые комментарии? Хотя вот этого господина на следующем фото явно что-то порадовало в распечатке.  Наконец, подходим к новейшей истории, когда компьютеры получили повсеместное распространение, а программирование перестало быть таким специфическим занятием. Код программы стало очень просто создать, подправить, а также снабдить комментариями.  Главное — пользоваться этой возможностью разумно. Потому что нет ничего хуже, чем карта, которая не соответствует местности, или комментарий, который немного не так описывает код: Но так ли часто программисты используют комментарии вообще и забавные в частности? Точной статистики нет. Ради интереса я посмотрел процент (от общего числа строк) использования комментариев в коде нашего анализатора PVS-Studio с разбивкой по языкам программирования: Не знаю, какие выводы тут можно сделать. C# разработчики в PVS-Studio более ленивы, чем С++, и поэтому слабо комментируют код? :) Или, наоборот, их код настолько крут и интуитивно понятен, что там особо нечего пояснять? Я посмотрел некоторые комментарии, все довольно серьёзные. Ну, разве что во многих местах попалось классическое: "Не трогать!!!". Я рад, что ничто человеческое не чуждо и нашим разработчикам. Ну а как всё же обстоят дела с забавными комментариями у других разработчиков? В интернете можно найти много всего на эту тему. Мне приглянулся весьма старый, но популярный вопрос, заданный на Stack Overflow: "What is the best comment in source code you have ever encountered?". Там 518 ответов. Пару примеров оттуда я уже использовал ранее в этой статье.  Сначала я планировал составить рейтинг из самых эпичных комментариев, основываясь на популярности ответов. Но, полистав ответы с низким рейтингом, понял, что и там есть довольно смешные комментарии. Поэтому я просто прошёлся по списку и выбрал некоторые понравившиеся лично мне ответы. Выборка не претендует на полноту и объективность. Хочу заметить, что некоторые из оставленных пользователями Stack Overflow ответов очень эмоциональны и даже содержат ненормативную лексику. Поэтому я не всегда буду приводить их текст, а дам только ссылку. Но часто там содержатся действительно забавные вещи. Вот пример одного такого ответа. Также почти каждый ответ содержит обсуждение другими пользователями: вы можете переходить по ссылкам для ознакомления. Поэтичное Неожиданно начну с самого популярного ответа, набравшего 1460 голосов. Он содержит сразу два комментария. Первый был охарактеризован автором как "поэзия кода" (code poetry). Приведу его целиком: Великолепный образец привнесения мощной эмоциональной составляющей в бездушный код. Конечно, не стоит увлекаться такими посланиями на постоянной основе. Но, будучи встреченным единично, я уверен, такой комментарий способен вызвать только положительные эмоции. Интерактивное Второй комментарий из того же ответа добавляет частичку интерактива, немного геймифицируя рабочий процесс: Автор указал, что не обнародовал код, в котором содержится этот счётчик. Но, даже написанный для себя, он является отличным примером побуждающего к общению комментария. Магия кода "Я не знаю как, но это работает". Думаю, любой программист хотя бы раз в жизни оставлял что-то подобное в своём коде. Я оставлял. Один из вариантов такого классического комментария: Подобные комментарии встречаются и в других ответах, например: И ещё пример: Кстати, я тот свой "магический" код просто скопировал откуда-то, но так и не смог понять, как же он работает. :) Непознанное Разработчики часто переоценивают сложность своего кода. В результате появляются подобные комментарии: Возможно, автор и сам ничего там не понял. Ещё пример: Ну это ещё надо на код взглянуть. Наконец, немного отсылок к Данте никогда не повредит: Девятый круг. Только попробуй! Интересны комментарии, прямо запрещающие правку кода. Или предупреждающие о негативных последствиях этого. Пример: Довольно изощрённо оставлять такое в обычном (не автоматически сгенерированном) коде, не находите? А вот более развёрнутый обстоятельный вариант совета отказаться от правок: Есть пример комментария, запрещающего удаление комментария: Ещё одно недвусмысленное предупреждение: И напоследок в этом блоке: Работает – не трогай. Цифровое одиночество Не зря я столько распинался в начале про нехватку человеческого общения и эмоциональный голод. Как вам такое? Или такое? А вот тоже просьба, но к кому или чему? Да, программисты — они такие: изобретательны, с отличным чувством юмора, но часто одиноки и пытаются поговорить хотя бы с машиной. Стариковское Не менее остро стоит проблема смены поколений. Вот немного стариковского брюзжания: Да, в наше время всё было лучше. Отложим это на потом Прокрастинация — вот настоящий бич современности. Конечно, программистов тоже не минула эта напасть. Пример весьма своеобразной метки TODO в коде: Ни в коем случае не поддерживаю такого поведения. Но все мы люди, в конце концов. Ещё комментарий с TODO, но что-то пошло не так: Зато есть повод поговорить. Если непонятно, что делать или что написать в комментарии: Если не хочется писать большой комментарий: А если сейчас некогда и комментировать, то вот: Пойду лучше посплю. Для особо непонятливых Куда же без комментариев в стиле Капитана Очевидность (Captain Obvious). Один из вариантов: Ещё пример: Да, без разъяснений тут явно не обойтись. Спасибо, Кэп. Сделай код ещё веселее Встретил несколько примеров конструкций, основанных на комбинации ключевых слов языка программирования, имён переменных и комментариев. Выглядит очень забавно. Вариант такого комментария: Другой пример: А вот довольно двусмысленный вариант: Судя по комментарию, автор тоже считает конструкцию двусмысленной. И ещё один пикантный комментарий, раз уж мы затронули эту тему: Главное, что не ушла в минус. Невиновен! За многими комментариями стоит определённая история. Например, как в следующем примере. Поэтому иногда советую переходить по ссылкам для ознакомления. Здесь вариант классического отказа от ответственности: Ещё один отказ от ответственности (и пасхалка для следующего разработчика): А мне нравится 42. Ещё встретился вариант с частичным признанием вины: А ты большой хитрец, Paul. Как я уже говорил, у разработчиков тяжёлая работа: Зато по ночам никто не отвлекает. Время для кофе Не желаете немного кулинарного юмора? Ну и куда же без кофе? Почему сельдерей увядший? Ответ по ссылке: Мы за здоровое питание. Не своё – не жалко Прокомментировать чужой код? Легко! Мне встретились примеры от довольно безобидных: До максимально эмоциональных. Это тот самый случай, когда я приведу только ссылку. Осторожно, там много боли. Интересно, что код и комментарии обнародовал вовсе не их автор. Он случайно нашёл этот ответ на Stack Overflow, после чего решил дать разъяснения. Свой код тоже часто комментируют весьма эмоционально. Особенно, если это Quake III и там делается техножесть. Снова привожу только ссылку. Когда ты Кармак. Иногда простого текста мало Тогда для передачи всей гаммы чувств нам на помощь приходит старая добрая псевдографика. Мимо такого просто невозможно пройти: И ещё пара не менее креативных комментариев. Даю ссылку и ссылку, так как не уверен, что при копировании текста всё не разъедется. А потом они удивляются, что исходный код такой большой. Вместо тысячи слов Оставлять максимально лаконичные комментарии – это здорово. Но здесь немного перестарались: После такого самое время отдохнуть: И пофилософствовать: Зато силы на написание кода остались. Страшное (нет) Немного кибермистики я обнаружил в таком комментарии: Дальше смешанные чувства: страшно, но интересно: Главное дизассемблер не призвать. Разное И ещё немного комментариев, которые не удалось выделить в какую-то отдельную группу. История релизов от разработчика. Закрытая частная версия: Зато не обманули с подарком. Вообще, комментарии обычно неотделимы от кода. Но бывают исключения: На все случаи жизни. Я проверял. А здесь кому-то не хватило комментариев. И он указывает на это в комментарии: Когда вся твоя жизнь в комментариях. Юридическая поддержка никогда не помешает: Уволен! Напоследок хочу привести два особо ёмких комментария, в которых словно сосредоточилась вся мудрость и философия программирования. Первый: И второй: На этом у меня всё. Думаю, понятно, что тема комментариев в коде поистине неисчерпаема. Можно найти ещё миллион смешных и не очень примеров. Комментируйте свой и чужой код, не держите в себе. Делайте это весело. И пожалуйста, не забывайте исправлять грамматические ошибки в комментариях именно в день релиза (старая шутка). Спасибо за внимание: Если хотите поделиться этой статьей с англоязычной аудиторией, то прошу использовать ссылку на перевод: Sergey Khrenov. Code comments as a work of art. COO