Приветствую всех программистов, а также сочувствующих.
Кто из нас хотя бы раз в жизни не оставлял комментарии в коде? Это был ваш код или, может быть, чей-то еще? Какие комментарии вы писали: полезные или нет? А может быть, они были забавными, чтобы порадовать коллег или тимлида на очередном обзоре? Попробуем немного подумать и дать ответы на эти вопросы в формате небольшой заметки.
Давайте попробуем понять, что движет людьми, комментирующими их программу.
Мы сосредоточимся на нестандартных, забавных комментариях.
Мы приготовили для вас несколько замечательных примеров.
Идти.
Введение
Все большие серьезные исследования обычно начинаются с экскурса в историю.И чем глубже экскурсия, тем лучше.
Я не буду отступать от традиций.
Но сначала поговорим немного о предметной области — программировании и комментировании кода.
Я думаю, никто не станет оспаривать тот факт, что программирование – это творческая деятельность.
Сродни письму, с примесью технологий и философии.
Современная программа — это, по сути, «книга» инструкций для компилятора или виртуальная машина и компилятор.
Это несколько упрощенно, но я хочу передать основную мысль: эту «книгу» с кодом читает не только машина, но и человек.
При этом человек не только смотрит, но и редактирует код, что требует много времени и усилий.
Поэтому, несмотря на наличие элементов творчества, работа программиста все равно может быть вполне рутинной.
Поэтому эмоциональная составляющая очень важна.
Человек – существо социальное.
Какое может быть живое общение с машиной? И как радостно во время работы с кодом наткнуться на сообщение самому себе с какими-то пояснениями или забавными комментариями.
Еще лучше, если сообщение вам оставил другой разработчик.
При этом он, возможно, не ожидал, что оставляет комментарий специально для вас.
Чувствуете драматичность? Теперь вы уже общаетесь.
Часто - совершенно незнакомые люди.
Но вот так, плюнув на ладони, вы взяли в руки воображаемые лопаты и словно вместе работали.
Вы разбираетесь в тонкостях кода и пытаетесь понять, как он вообще работает. Оставляйте друг другу советы и забавные пасхалки.
Владение и командная работа в действии.
Наконец, зачастую необходимо просто выплеснуть накопившиеся эмоции.
А если эти эмоции связаны с кодом, то комментарии позволяют зафиксировать что-то вроде:
//Dear future me. Please forgive me. //I can't even begin to express how sorry I am.
Немного истории
Вернемся к истории, желательно древней истории, и не забудем о письменности.Что может быть древнее слова? Ну тот же самый, что был в начале.
Ученые, однако, утверждают, что здесь была наскальная живопись.
Это неосознанное желание даже древнего человека передать послание своим братьям или потомкам.
Покажите свой быт, обычаи, запечатлейте сцены охоты и отдыха.
Некий комментарий к моей повседневной и такой непростой жизни.
Да, мы сделали все возможное.
Но они это сделали! 
Дальше произошло другое.
История развития письменности интересна и неоднозначна.
По современным представлениям считается, что центров его возникновения было несколько.
Подробнее об этом можно прочитать, например, в статья из Википедии.
Но как бы то ни было, человечество прошло долгий путь от нанесения простых рисунков на глиняных табличках (Месопотамия) до современных цифровых методов генерации текста.
Включение текста комментариев в код. Кстати, о технологии: здесь статья об истории развития компьютеров из той же Википедии.
Не благодари меня.
И вот он – 20 век с его бурным развитием технологий.
Первые механические, а затем электронные компьютеры.
Кстати, а вы знали, что Мерседес тоже производит арифмометры? Я не знал.
Конечно, поначалу отзывы о программах были не очень хорошие.
Я не думаю, что они вообще об этом думали.
Долгое время перфокарты использовались для реального программирования.
Конечно, можно прямо на них написать что-нибудь смешное, например: «Ой, ребята, посмотрите, какой классный узор из дырок».
Но кто это оценит? 
Первые компьютеры были огромными, сложными и использовались для очень серьезных вычислений.
И программисты им под стать.
Что за смешные комментарии бывают? Хотя этот господин на следующем фото явно был чем-то доволен в распечатке.
Наконец, мы подходим к недавней истории, когда компьютеры получили широкое распространение и программирование перестало быть таким уж специфичным занятием.
Программный код стало очень легко создавать, исправлять, а также комментировать.
Главное – использовать эту возможность с умом.
Потому что нет ничего хуже, чем карта, не соответствующая местности, или комментарий, немного неправильно описывающий код: /**
* Always returns true.
*/
public boolean isAvailable() {
return false;
}
Но как часто программисты используют комментарии вообще и смешные в частности? Точной статистики нет. Ради интереса я посмотрел процент (от общего количества строк) использованных комментариев в коде нашего анализатора PVS-Studio в разбивке по языкам программирования:
- C++: около 1 082 000 строк, 15% комментариев;
- C#: около 509 000 строк, 6% комментариев;
- Java: около 80 000 строк, 16% комментариев.
Неужели C#-разработчики в PVS-Studio ленивее, чем C++, и поэтому плохо комментируют код? :) Или наоборот, их код настолько крут и интуитивно понятен, что объяснять особо нечего? Посмотрел некоторые комментарии, все вполне серьезно.
Ну разве что во многих местах я встречал классику: «Не трогай!!!» Я рад, что ничто человеческое нашим разработчикам не чуждо.
Примеры комментариев
А как насчет забавных комментариев других разработчиков? В Интернете можно найти много информации по этой теме.Мне понравился очень старый, но популярный вопрос, заданный на Stack Overflow: " Какой самый лучший комментарий в исходном коде вы когда-либо встречали? Ответов 518. Пару примеров оттуда я уже использовал ранее в этой статье.
Сначала я планировал ранжировать самые эпичные комментарии по популярности ответов.
Но, просматривая ответы с низким рейтингом, я понял, что и там были довольно забавные комментарии.
Поэтому я просто просмотрел список и выбрал некоторые ответы, которые понравились лично мне.
Выборка не претендует на полноту и объективность.
Хочу отметить, что некоторые ответы, оставленные пользователями Stack Overflow, очень эмоциональны и даже содержат ненормативную лексику.
Поэтому я не всегда буду приводить их текст, а лишь дам ссылку.
Но часто там случаются действительно забавные вещи.
Здесь пример один такой ответ. Также почти каждый ответ содержит обсуждение других пользователей: вы можете перейти по ссылкам, чтобы прочитать его.
Поэтический Неожиданно начну с самых популярных отвечать , получивший 1460 голосов.
Содержит сразу два комментария.
Первый был охарактеризован автором как «код поэзии».
Процитирую его полностью: /**
* For the brave souls who get this far: You are the chosen ones,
* the valiant knights of programming who toil away, without rest,
* fixing our most awful code. To you, true saviors, kings of men,
* I say this: never gonna give you up, never gonna let you down,
* never gonna run around and desert you. Never gonna make you cry,
* never gonna say goodbye. Never gonna tell a lie and hurt you.
*/
Отличный пример привнесения мощной эмоциональной составляющей в бездушный код. Конечно, не стоит увлекаться подобными сообщениями на постоянной основе.
Но, столкнувшись всего один раз, я уверен, что такой комментарий сможет вызвать только положительные эмоции.
Интерактивный Второй комментарий от того же отвечать добавляет немного интерактивности, слегка геймифицируя рабочий процесс: //
// Dear maintainer:
//
// Once you are done trying to 'optimize' this routine,
// and have realized what a terrible mistake that was,
// please increment the following counter as a warning
// to the next guy:
//
// total_hours_wasted_here = 42
//
Автор указал, что не обнародовал код, содержащий этот счетчик.
Но, даже написанный для себя, это отличный пример комментария, поощряющего общение.
Магия кода «Я не знаю как, но это работает».
Думаю, каждый программист хотя бы раз в жизни оставлял в своем коде что-то подобное.
Я ушел.
Один из параметры этот классический комментарий: //When I wrote this, only God and I understood what I was doing
//Now, God only knows
Подобные комментарии появляются в других ответах, Например : // Magic. Do not touch.
И далее пример : // I put on my robe and wizard hat.
Я, кстати, просто скопировал откуда-то этот «волшебный» код, но так и не смог понять, как он работает. :) Неизвестный Разработчики часто переоценивают сложность своего кода.
В результате подобные Комментарии : /* You are not meant to understand this */
Возможно, автор сам там ничего не понял.
Более пример : /**
* If you don't understand this code, you should be flipping
* burgers instead.
*/
Ну, код еще надо посмотреть.
Окончательно, Немного Отсылка к Данте никогда не помешает: //Abandon all hope ye who enter beyond this point
Девятый круг.
Просто попробуйте! Интересные комментарии, которые прямо запрещают редактировать код. Или предупреждение о негативных последствиях этого.
Пример : // Autogenerated, do not edit. All changes will be undone.
Довольно сложно оставлять что-то подобное в обычном (не автоматически сгенерированном) коде, вам не кажется? Но вот более подробный, подробный вариант совет отказаться от правок: /*
* You may think you know what the following code does.
* But you dont. Trust me.
* Fiddle with it, and youll spend many a sleepless
* night cursing the moment you thought youd be clever
* enough to "optimize" the code below.
* Now close this file and go play with something else.
*/
Есть пример комментарий, запрещающий удаление комментария: // If this comment is removed the program will blow up
Еще один однозначный предупреждение : // I know the line below is wrong, but it came that way from our IP
// vendor, and the driver won't work if you "fix" it. I've had to
// revert this change 4 times now. Leave it alone, or
// I will hunt you down and hurt you
И наконец в этом блоке: // (c) 2000 Applied Magic, Inc.
// Unauthorized use punishable by torture, mutilation, and
// vivisection.
Работает - не трогайте.
Цифровое одиночество Я не зря в начале так много говорил о недостатке человеческого общения и эмоциональном голоде.
Как вам это нравится такой ? // sometimes I believe compiler ignores all my comments
Или такой ? //Mr. Compiler, please do not read this.
И здесь тоже запрос , но кому или чему? /* Please work */
Да, программисты такие: изобретательные, с отличным чувством юмора, но часто одинокие и пытающиеся хотя бы поговорить с машиной.
Стариковское Не менее острой является проблема смены поколений.
Здесь маленький старичок ворчит: * .
and don't just declare it volatile and think you've solved
* the problem. You young punks think you know what volatile
* means. why in my day we had to cast it volatile uphill
* both ways, and the code still didn't work! Whippersnappers.
Да, в наше время все было лучше.
Давай отложим это на потом Прокрастинация – настоящий бич нашего времени.
Разумеется, от этой напасти не обошли и программистов.
Пример очень своеобразная пометка TODO в коде: // drunk, fix later
Я никоим образом не поддерживаю такое поведение.
Но в конце концов мы все люди.
Более комментарий с TODO, но что-то пошло не так: // TODO: Fix this. Fix what?
Но есть повод поговорить.
Если не понятно , что делать или что написать в комментарии: // TODO make this work
Если вы не хотите писать много комментарий : // THE LOOP THAT DO EVERYTHING!!!!!!!
А если сейчас нет времени комментировать, то Здесь : -- Comment this later
Мне лучше пойти и поспать.
Для особо непонятливых Без комментариев в стиле Капитана Очевидность.
Один из вариантов: return 1; # returns 1
Более пример : i++; // increment variable i
Да, без уточнений явно не обойтись.
Спасибо, Кэп.
Сделайте свой код еще веселее Мне встретилось несколько примеров конструкций, основанных на сочетании ключевых слов языка программирования, имен переменных и комментариев.
Выглядит очень забавно.
Вариант такой комментарий: long john; // silver
Другой пример : long long ago; /* in a galaxy far far away */
Но это весьма неоднозначно вариант : double penetration; // ouch
Судя по комментарию, автор тоже считает конструкцию неоднозначной.
И еще один пикантный комментарий , раз уж мы по теме: virgin = 0; /* you're not a virgin anymore, sweety */
Главное, чтобы оно не ушло в минус.
Невиновный! За многими комментариями стоит история.
Например, как в следующем примере.
Поэтому иногда советую перейти по ссылкам для знакомства.
Здесь вариант классический отказ от ответственности: // I am not responsible of this code.
// They made me write it, against my will.
Другой отказ отказ от ответственности (и пасхалка для следующего разработчика): /*
This isn't the right way to deal with this, but today is my last
day, Ron just spilled coffee on my desk, and I'm hungry, so this
will have to do.
*/
return 12; // 12 is my lucky number
А мне нравится 42. Я тоже встречала вариант с частичным признанием вины: // If this code works, it was written by Paul DiLascia. If not,
// I don't know who wrote it
А ты большой хитрец, Пол.
Как я уже сказал, разработчики тяжелый Работа: // This is crap code but it's 3 a.m. and I need to get this working.
Но ночью ничто не отвлекает. Время для кофе Хотите немного кулинарный юмор? } catch (PartInitException pie) {
// Mmm. pie
Ну куда же мы без кофе ? // need a coffee to fix this.
Почему сельдерей вянет? Ответить от связь : // Wilted celery?
Мы за здоровое питание.
Не твое - не обращай внимания Комментировать чужой код? Легко! Я встречал примеры из довольно безвредный : // This only exists because Scott doesn't know how to use const
// correctly
До максимального эмоционального уровня.
Это тот самый случай, когда я только подарю связь .
Будьте осторожны, там очень больно.
Интересно, что код и комментарии не были обнародованы их автором.
Этот ответ он случайно нашел на Stack Overflow, после чего решил дать разъяснения.
Они также часто довольно эмоционально комментируют свой код. Особенно, если это Quake III и там много всяких технологий.
Я просто процитирую еще раз связь .
Когда ты Кармак.
Иногда простого текста недостаточно Тогда для передачи всей гаммы чувств нам на помощь приходит старая добрая псевдографика.
Прошлое такой Пройти просто невозможно: ## Safety pig has arrived!
## _
## _._ _._ .
-', _._(`)) ## '-.
` ' /-.
_.-' ',/ ## ) \ '.
## / _ _ | \ ## | a a / | ## \ .
-.
; ## '-('' ).
-' ,' ; ## '-; | .
' ## \ \ / ## | 7 .
__ _.-\ \
## | | | ``/ /` /
## /,_| | /,_/ /
## /,_/ '`-'
##
И еще пара не менее креативных комментариев.
Я даю связь И связь , потому что не уверен, что при копировании текста всё не развалится.
А потом удивляются, что исходный код такой большой.
Вместо тысячи слов Оставлять как можно более краткие комментарии — это здорово.
Но здесь мало перестарался : // HERE
После этого пришло время расслабляться : // zzzzZZZZzzzz.
И философствовать : # let's pretend we are free, for a while
Но у меня еще были силы писать код. Страшно (нет) Я обнаружил немного кибермистицизма в так Комментарии: // This will save us ~0.5 sec for every user and please the machine spirits.
Дальше возникают смешанные чувства: страшно, но Интересный : // Choose! Choose the form of the Destructor!
// The choice is made! The Traveler has come!
Главное не вызывать дизассемблер.
Разнообразный И еще несколько комментариев, которые не удалось выделить в отдельную группу.
История релизов от разработчика.
Закрытое частное версия : //3.4 JeK My manager promised me a lap dance if I can fix this
// release
//3.5 JeK Still waiting for that dance from my manager
//3.6 JeK My manager got changed, the new manager is hairy, dont
// want the dance anymore
//3.7 Jek Got that dance, yuck!
Но с подарком меня не обманули.
Вообще комментарии обычно неотделимы от кода.
Но есть исключения : // This comment is self explanatory.
На все случаи жизни.
Я проверил.
И здесь кто-то было недостаточно Комментарии.
И он отмечает это в комментарии: //Please comment on your source code
Когда вся твоя жизнь в комментариях.
Юридический поддерживать никогда не помешает: /* My lawyer told me not to reveal */
Уволенный!
Заключение
Напоследок хотелось бы дать два особенно емких комментария, в которых, казалось бы, сконцентрировалась вся мудрость и философия программирования.
Первый : 'NO COMMENT
И второй : // nobody read comments!
Это все, что у меня есть.
Думаю, понятно, что тема комментариев в коде поистине неисчерпаема.
Можно найти еще миллион смешных и не очень примеров.
Комментируйте свой и чужой код, не держите его при себе.
Сделайте это весело.
И, пожалуйста, не забудьте исправить грамматические ошибки в комментариях в день релиза (старая шутка).
Спасибо внимание : // good luck!
Если вы хотите поделиться этой статьей с англоязычной аудиторией, воспользуйтесь ссылкой для перевода: Сергей Хренов.
Комментарии к коду как произведение искусства .
Теги: #программирование #stackoverflow #pvs-studio #Codebred #юмор #комментарии
-
Жесткий Чехол Для Ipad И Преимущества
19 Oct, 24 -
Тактовая Частота Генерации Примитивов Lut
19 Oct, 24 -
Персональный Компьютер В Гостиной
19 Oct, 24 -
Приобретение Аккаунта Plus На Vimeo.com
19 Oct, 24 -
С Какого E-Mail Лучше Отправлять Рассылки?
19 Oct, 24
