«Смешные комментарии» - плохая практика или нет? [закрыто]

Я хочу спросить вас, является ли добавление некоторых «пасхальных яиц» в исходную документацию непрофессиональным или нет. Возможно, вы читали опрос StackOverflow для забавных комментариев в исходной документации, и я лично сталкивался со многими такими вещами во время моей работы, включая забавные (или нет) вещи в общедоступной документации API (например, этот слабый BZZZTT !! 1! Вещь в публичной документации по Android я могу привести как минимум еще десяток примеров).

Я не могу прийти к окончательному мнению для себя, потому что у меня есть противоречивые аргументы самостоятельно.

Pro аргумент:

• Это может поднять настроение кому-то и сделать его / ее день более смешным / более продуктивным. Большую часть исходного кода не нужно комментировать в любом случае (если проект выполнен правильно), потому что конкретный метод (например) не требует пояснений, или если это куча странного дрянного кода, он не может объясняться осмысленно, чтобы забавная шутка не повредила возможной информации, которую вы можете получить из документа.

Минус аргумент:

• Если вы очень сконцентрированы / разочарованы, последнее, что вам нужно, это чья-то глупая шутка, вместо того, чтобы дать вам необходимую информацию о документированной части кода, это может сделать вас еще более разочарованным. И идея о том, как будет выглядеть документация, если все начнут это делать, ужасна. Кроме того, парень, который пишет шутку, может быть единственным, кто думает, что это смешно / интересно / стоит тратить время на ее чтение.

Что вы думаете?

Я думаю, что забавные комментарии тратят впустую время - напрасно потратили время на запись, напрасно потратили время на чтение, потратили время, чтобы показать своим коллегам забавное замечание, которое (почти всегда) просто озадачивает и так далее.

Но ... на самом деле никто не работает на 100% весь день каждый день (такие сайты были бы пустыми, если бы мы это делали), и подлинный юмор расстраивает день и помогает поддерживать моральный дух.

Я все равно проголосовал бы против этого просто потому, что каждый «забавный» комментарий, который я когда-либо читал, мог быть веселым в то время - но я еще не видел один действительно забавный комментарий, большинство просто озадачивают или глубоко в -joke.

Если бы забавные комментарии были действительно забавными, это изменило бы мое мнение. Но как только вы поощряете шутки, вы поощряете ругань, оскорбления или злобу?

Я большой поклонник забавных комментариев .

Вы всегда должны быть профессиональны в своих комментариях, но какой-то юмор не убьет читателя.

Особенно, если читатель является членом вашей команды.

Что мне больше всего не нравится, так это разработчики, которые относятся к себе слишком серьезно. Я думаю, что мы должны повеселиться на работе, или работа не стоит того.

Если это имеет значение, хорошо быть смешным. Объяснять что-то в комментарии забавным способом - это хорошо. Однако, если это только что-то смешное и не содержит никакой реальной ценности в качестве комментария, это просто раздражает. Всегда имейте в виду, что причина комментариев - сделать обслуживание более эффективным. Юмор не должен конфликтовать с этим, но может, если не будет сделано должным образом.

Код предназначен для чтения ... много раз.

Сколько вы знаете шуток, которые смешны после сотого рассказа?

Смешные комментарии - это здорово.

• Это придаст позитивный вид вашему на первый взгляд скучному коду.
• Если вы правильно рассчитали время. Это объясняет гораздо лучше, чем обычный скучный комментарий. Под «временем» здесь я подразумеваю отношение к коду под комментарием.
• Ваш код запомнится многим, потому что эмоциям отводится лучшее место в (человеческой) памяти. Это отличный трюк, если вы хотите, чтобы с вами работало больше парней над проектом с открытым исходным кодом.
• Вообще полезно в обзорах. Это делает ваш код намного более терпимым. Конечно, вы должны сначала сосредоточиться на написании хорошего кода. Я чувствую, когда кто-то уверен в коде, который они пишут, забавные комментарии - просто побочный эффект.

Только не будь смешным, как этот парень ;)

Вот что я написал в два часа ночи («DQ» - инициалы моей компании):

// Twas the night before go-live and all through DQ
// the devs were all crying and yes, this means you.
// Keys had been saved with both hyphens and 'scores
// which left this programmer with finger pad sores.
// The solution I crafted, you'll likely find lacking:
// to OR them together with judicuous hacking.

$hyphenated = str_replace('_','-',$data_type_key);
$underscored = str_replace('-','_',$data_type_key);
// (and then see line 46)

Если бы вы просматривали свой исходный код перед заказчиком, вы бы смутились?

Ни один из текущих ответов, кажется, не принимает это во внимание. Некоторые клиенты не имеют чувства юмора и воспримут шутки как показатель того, что вы не относитесь к своей работе серьезно. Они сделают вывод, что вы небрежны с вашей работой.

Смешные комментарии к коду иногда могут быть непрофессиональными и неуместными.

Помимо того, что уже было сказано, если вы работаете в международной команде, некоторые из ваших зарубежных коллег могут не получить шутку, потому что они связаны с некоторыми местными культурными ссылками или игрой слов, которые не понимают те, для кого английский не является родным языком. , То же самое относится и к проектам с открытым исходным кодом.

Если это эффективно и не тратит время читателей (в чтении / понимании), то я не вижу проблемы с небольшим количеством юмора.

Точно так же, как шутки в реальном мире, если вы делаете их постоянно, это не смешно, не продуктивно и не профессионально. Но есть время и место для всех шуток, и есть время и место в коде. Как и в реальном мире, он знает, где, когда и как пошутить.

Зависит от того, что для заданий в колледже я почти всегда делал забавные комментарии, так как знал, что это никогда не будет использоваться, и это просто домашнее задание.

Для более серьезных проектов я бы все еще использовал их здесь и там, но не так широко, чтобы это раздражало или было трудно понять, бросая вызов цели комментария.

Я помню, как занимался веб-программированием, где мне приходилось избегать несовместимости браузеров и странных глюков. Иногда это заканчивалось комментариями, полными ярости и ненависти в .jsфайлах.

Мое основное правило: если совершенно очевидно, что делает этот раздел кода, включите смешные комментарии!

Если код настолько неясен и запутан, как ад (например, « встроенный класс »), я бы лучше использовал комментарии, которые я пойму сам через пару дней ...