Це «смішне коментування» - це погана практика чи ні? [зачинено]

Хочу запитати вас, чи додавати якісь «писанки» у вихідну документацію непрофесійно чи ні. Напевно, ви прочитали опитування StackOverflow для смішних коментарів у вихідній документації, і я особисто натрапив на багато таких речей під час своєї роботи, включаючи смішні (чи ні) речі в публічній документації API (наприклад, ця слабка BZZZTT !! 1! Річ в публічній документації на Android я можу навести хоча б десяток прикладів).

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

Про аргумент:

• Це може підбадьорити когось і зробити його день веселішим / продуктивнішим. Більшу частину вихідного коду ніяк не потрібно коментувати (якщо проект виконано належним чином), оскільки конкретний метод (наприклад) пояснює себе, або якщо це купа дивного хитрого коду, він не може бути поясненим змістовно, тому смішний жарт не шкодить можливій інформації, яку ви можете отримати у документа.

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

• Якщо ви дуже концентровані / розчаровані, останнє, що вам потрібно, - це чийсь дурний жарт, замість того, щоб давати вам необхідну інформацію про задокументовану частину коду, це може просто зробити вас ще більш засмученими. І думка про те, як виглядатиме документація, якщо всі починають це робити, жахлива. Плюс хлопець, який пише жарт, може бути єдиним, хто думає, що це смішно / цікаво / варто витрачати час на його читання.

Як ти гадаєш?

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

Але ... ніхто насправді не працює на 100% кожен день (подібні сайти були б порожніми, якби ми), а справжній гумор порушує день і допомагає підтримувати мораль.

Я б все ще голосував проти, просто тому, що кожен "смішний" коментар, який я коли-небудь читав, напевно, може бути смішним на той час, - але я ще не бачив такого, який насправді смішний, більшість - просто спантеличені або є глибоким вниз -жартувати.

Якби смішні коментарі були насправді смішними, це змінило б мою думку. Але як тільки ви заохочуєте жарти, чи заохочуєте ви лаяння чи образи чи злість?

Я великий шанувальник смішних коментарів .

Ви завжди повинні бути професійними в коментарях, але якийсь гумор не вб'є читача.

Особливо, якщо читач є членом вашої команди.

Мені найбільше не подобається, це розробники, які сприймають себе занадто серйозно. Я думаю, що нам слід розважитися на роботі, або працювати не варто.

Якщо це має значення, це чудово буде смішно. Пояснювати щось у коментарі кумедно - це чудово. Однак, якщо це лише щось смішне і не містить фактичного значення як коментар, це просто дратує. Завжди пам’ятайте, що причиною коментарів є підвищення ефективності обслуговування. Гумор не повинен суперечити цьому, але міг би бути, якщо його не зробити належним чином.

Код призначений для читання ... багато разів.

Скільки анекдотів вам відомо, що після сотої розповіді смішно?

Смішні коментарі чудові.

• Це дає позитивну атмосферу вашому, здавалося б, нудному коду.
• Якщо ви правильно зрозуміли свій термін . Це пояснює набагато краще, ніж звичайний нудний коментар. Під "таймінгом" тут я маю на увазі відповідність коду нижче коментаря.
• Ваш код запам’ятається багатьом, адже емоціям надається краще місце в (людській) пам’яті. Це чудова хитрість, якщо ви хочете, щоб більше хлопців працювали з вами над проектом з відкритим кодом.
• Як правило, корисно в оглядах. Це робить ваш код набагато більш прийнятним. Звичайно, спершу слід зосередитись на написанні хорошого коду. Я відчуваю, коли хтось впевнений у коді, який вони пишуть, смішні коментарі - лише побічний ефект.

Просто не будь смішним, як цей хлопець ;)

Ось один я написав о другій ранку ("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файлах.

Моє основне правило: Якщо дещо очевидно, що робить розділ коду, ВИМОГАЮТЬ КОМЕНТАРИ!

Якщо код настільки незрозумілий і примхливий, як пекло (як " клас вбудованих "), я б краще використовувати коментарі, я зрозумію себе через пару днів ...