Мій клієнт хоче 25% коментарів до мого поточного проекту, як реагувати? [зачинено]

молодший розробник тут.

Наразі я сам працюю над веб-додатком для великого клієнта моєї компанії. Я почав минулого місяця. Клієнт хоче хоча б 25% коментарів у кожному із своїх програмних проектів.

Я перевірив код попередніх програм і ось мої спостереження:

• кожен файл починається з блоку коментарів (пакет, дата останнього оновлення, назва моєї компанії та авторські права)

• всі змінні коментуються своїми іменами // nameOfCustomer public String nameOfCustomer

• коментуються всі геттери та сетери

• дуже мало корисних коментарів

Схоже, розробники просто розміщують стільки коментарів, скільки можуть досягти межі 25%, незалежно від якості та корисності. Моя компанія каже мені, що "ми робимо це так, як хоче клієнт".

Я не говорив про це безпосередньо з клієнтом. Ось мої аргументи поки що:

• марні рядки для читання та написання (втрата часу)
• коментарі іноді не оновлюються (джерело плутанини)
• розробники рідше використовують або довіряють справжнім корисним коментарям

Яка ваша порада з цього приводу? Як мені впоратися з ситуацією?

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

Основним принципом цієї відповіді є: "Радуйте замовника". Задоволення замовника означає не просто задоволення його очікувань; це означає розуміти їхні прохання настільки глибоко, що ви можете інтерпретувати те, що вони говорять, так, як вони це означають, і виконуючи вище та поза тим, що вони просять. Здається, інші відповіді керуються принципом зловмисного дотримання, який я вважаю огидним; і крім того, це сумнівна ділова практика, оскільки це поганий спосіб отримати багаторазових клієнтів.

Мені, коли я чую, як клієнт каже: "Я хочу 25% коментарів", це початок діалогу. Для мене зрозуміло, що тут йдеться про "я хочу багато описового тексту, щоб новачки до цієї кодової бази могли швидко працювати і працювати", а не "я хочу, щоб ви додали випадковість у певну синтаксичну категорію", як інші відповіді здається, приймають його. І я ставлюся до цього запиту серйозно і маю намір написати багато описових, корисних коментарів, спрямувавши новачків до структури коду, вказавши на дивовижні інженерні рішення та виклавши міркування, що входили в них, та надавши англійську на високому рівні описи складних розділів коду (навіть якщо вони не мають сюрпризів). Цей намір і розуміння є відправною точкоюдискусії - це ще до того, як ми навіть почнемо говорити. Для мене сенс запиту є настільки зрозумілим, що він навіть не потребує такого роз'яснення; але якщо вам це незрозуміло, ви, звичайно, повинні завітати до них!

Гаразд, так куди йде діалог, якщо це початкова точка? Наступна частина діалогового вікна проходить так:

1. Я б очікував, що це буде серйозними додатковими зусиллями, можливо, на другій фазі проекту, тобто над виробництвом інструменту, над яким вони працюють. Може пройти кілька хвилин дискусії, щоб обговорити цей процес та чому він є додатковою роботою, але я збираюся його опустити тут, оскільки як професійний програміст я очікую, що ви знаєте, як важко робити хороші коментарі.
2. "Серйозні додаткові зусилля" означають, що нам може знадобитися більший бюджет часу та більший грошовий бюджет; або нам може знадобитися зменшити бюджет функції; абонам може знадобитися йти на компроміс щодо якості та кількості коментарів. Ця частина буде трохи переговором. Але, на мою думку, ви повинні бути дуже впевнені у витратах на цю додаткову роботу і переконатися, що це така важлива особливість для клієнта, що він готовий взяти на себе ці витрати. А якщо вони - чудові! Ви отримуєте додатковий час і гроші, і вони отримують якісні коментарі. Усі перемагають. І якщо виявиться, що функція коментування для них не настільки важлива, що вони готові втратити здатність хитатися віджетами або готові дозволити, щоб термін проскочив до пізнього Granuary, 20x6, то всі знову виграють: вони отримують продукт, який вони хочете, і вам не доведеться витрачати додаткові зусилля, необхідні для створення високоякісних коментарів.

Ось де я думаю, що діалог не повинен проходити:

3. Не загрожуйте клієнту неякісними коментарями. Нехай вони допоможуть вам вибрати той рівень зусиль, який вони хочуть витратити, і який вони готові заплатити. Не обіцяйте їм 25% коментарів, а потім повідомляйте, що ви маєте намір виконати цю обіцянку, автогенеруючи випадковість після створення проекту.
4. Не приховуйте своїх планів. Не обіцяйте їм 25% коментарів, а потім автогенеруйте випадковість, не говорячи їм, що ви збираєтеся робити. Коли вони помічають (якщо не), ви обоє втрачаєте великий час: вони незадоволені отриманим вами продуктом, і ви отримуєте негативні слова з вуст.
5. Не намагайтеся переконати їх, що вони не хочуть коментарів. Вони чітко хочуть коментарів. Обговоріть компроміси різних підходів: так! Обговоріть альтернативні способи зробити кодову базу новичкою: так! Скажіть їм, що вони не знають, чого хочуть: так, ні. Ви хочете працювати з ними, щоб отримати їм те, що вони хочуть; тож зрозумійте, що це таке, і з’ясуйте, як найкраще донести їх до бюджету, який вони затверджують, визначивши пріоритет із особливостями, які їх хвилюють найбільше, якщо у них недостатні ресурси.
6. Не виправдовуйтеся, як важко писати коментарі. Написати код важко; налагоджувальний код важкий; писати коментарі важко. Якби це було легко, вони б не наймали тебе. Просто пропустіть скарги та перейдіть до точки, яка їх хвилює, а саме як додаткові зусилля, які потребують, впливають на них.

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

Говорячи, дуже важливо, як визначені (тут погані) стандарти якості:

• Контрактні стандарти якості: доставлений код повинен відповідати, інакше це порушення договору. Немає вибору.

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

• Спеціальні критерії, визначені парою осіб у клієнта. Тут ви можете зайнятись дискусією. Є надія :-)

В цьому останньому випадку може бути певна гнучкість, і ви можете спробувати дипломатично зробити точку зору. Ось кілька аргументів, що відповідають критеріям замовника:

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

Але замість того, щоб виступати проти поганого та протистояти клієнту, ви можете просто просувати кращі підходи:

• Чистий код (запропонуйте книгу своєму замовнику: є переконливий розділ, присвячений коментарям та коду самодокументації).
• Документальна практика: Найскладніші речі для розуміння, а отже, і найцінніша інформація, наприклад, відношення та взаємодія між класами, краще зафіксовані в окремому документі (наприклад, у зображенні UML, а не в 1000 словах коментарів?)

Якщо замовник все ще не впевнений, ви можете запропонувати експериментальну альтернативу, використовуючи інструменти автоматичної генерації документації з коментарями, такими як javadocабо doxygen. Запропонуйте перенести фокус із кількості (25% коду) на якість (створити зрозумілий javadoc).

Клієнт хоче хоча б 25% коментарів у кожному із своїх програмних проектів.

Клієнт дійсно хоче 25% коментарів чи ваш клієнт хоче, щоб ваш код був максимально описовим?

ІМХО, клієнт знає, що хоче, але не те, що йому потрібно. Оскільки клієнт не сам розробник і отримує відгуки від своїх власних працівників / клієнтів, ваш клієнт бачить лише верхню частину айсберга.

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

Спробуйте поговорити з ним і підготуйте деякі фрагменти коду з добре написаним кодом, який пояснює себе, та ще один поганий написаний з коментарями. Всього кілька рядків. Покажіть це, якщо потрібно, і використовуйте його як малюнок до своїх слів.

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

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

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

Коли це станеться, можна зробити аргументи, що винні дві групи людей:

1. Люди, які ставлять межу - явно це надмірно і заважає людям подавати належним чином сформовану інформацію без додавання штучного шуму

2. Люди , які представили інформацію , яка була належним чином сформована, а потім додав штучний шум , коли система спонукало їх замість того, щоб додати більше фактичного речовини

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

Ця ситуація з коментарями майже однакова. Ваші розробники прийняли запит на коментарі та реалізували його, скидаючи випадковий шум у свій код. Документування назв змінних, що знаходиться поруч із декларацією змінних, - вандалізм . Такого ніколи не мало статися.

"Але як ще ми можемо досягти 25%?" Написавши фактичні коментарі по суті. Використовуйте більше слів, кращі слова, найкращі слова для документування ефекту функцій. Розкрийте свої пояснення. Опишіть крайові корпуси більш докладно.

Однак, повертаючись до початкової точки, і клієнт тут частково винен, оскільки "25% вихідного коду" є надзвичайно довільним. Зрештою, вони є клієнтом, тож зробіть це найкраще. Але я маю на увазі "найкращий". Не "найгірший", як це було досі.

Я не знаю, в чому велика суєта з цією вимогою.

Лише за допомогою базової доксигенації коду ви, мабуть, вже на 10%. І візьмемо ще 5% коментарів, які ви написали для себе (деякі пишуть більше, але 5% здається консервативною оцінкою, якщо ви не прийняли обітницю мовчання). На даний момент це близько 15% (так, так, я знаю, 5% з 90% менше 5%, не пилять). Якщо ваш доксиген менше 10%, можливо, ваші методи дуже довгі; Зазвичай це гарна ідея розбити їх на більш дрібні (переважно приватні / захищені), або використовувати більш загальні допоміжні класи тощо.

Тепер для решти тексту коментарів - розмістіть міркування щодо дизайну та сценарії використання в коментарях на рівні класу / файлу. Майте кілька таблиць або ASCII-арт (або код доксигену, який створює приємніші речі, коли вони надаються). Я, звичайно, не знаю, про що йдеться у вашому проекті, але я вважаю, що ви можете це зробити без жодних підступних коментарів (крім котла доксигенації) і дійти до чогось близького до 25%.

Якщо це, скажімо, 20%, а не 25% - я впевнений, що клієнт просто дав цю кількість як щось довільне, і буде добре з цим. У будь-якому разі поговоріть з ними, щоб обговорити, що слід включати коментарі; і покажіть їм приклад коментованого файлу, щоб побачити, чи задоволені вони. Якщо вони є, то це все, якщо вони думають, що чогось не вистачає, вони скажуть вам, чого не вистачає. Вони не збираються говорити вам: "Ми не можемо запропонувати будь-яких можливих додаткових коментарів, але ми все ще хочемо, щоб ви додали".

PS - Перегляньте стандартний код контейнерів Java, щоб побачити, як ви можете досягти, о, 70% або близько ...

Мати 25% коментарів у своєму коді - це відмінна мета, і це робить клієнта щасливим. Тепер писати 25% шалених коментарів із наповнювачами на кшталт "i + = 1; // збільшити i на 1" має бути під вами, тому витрачайте свій час, пишіть корисні коментарі та насолоджуйтесь відчуттям, що вам насправді заплачено зробити щось, що ви повинні зробити. все одно.

Ми всі знаємо, що це вимога в лайна. Тут цікаве питання

як реагувати?

Я дуже вірую у те, щоб зробити видимими проблеми. Тут я б використовував той факт, що гроші розмовляють.

Попросіть мене це зробити, і я скажу впевнений, що це додасть 1% до моєї ставки. О, але це додасть 20% до будь-яких подальших пропозицій щодо обслуговування.

Тільки раз вони запитують, чому я навчатиму їх, що суть добрих імен - це уникати необхідності коментувати.

В якості альтернативи я запропоную створити документацію, спрямовану на отримання програміста з технічного обслуговування з визначеним набором передбачуваної кваліфікації, щоб швидше реалізувати ідеї, що стоять за проектом. Або, звичайно, я можу дати вам 25% коментарів. До вас.

Так, я розумію ваше розчарування дурним правилом. Я читав багато програм з марними коментарями на кшталт

x = x + 1; // add 1 to x

І я кажу собі: Отже, що означає знак плюс !! Нічого, дякую, що сказали, я цього не знав.

Але це сказав, що клієнт оплачує рахунок. Тому ви даєте їм те, що вони хочуть. Якби я працював у автосалоні, і замовник сказав, що хоче пікап, я б не сперечався з ним про те, чи справді йому потрібен пікап, і перевірити його на те, що він очікує в ньому затягнути. Я б продав йому пікап.

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

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

Майте на увазі, що люди, з якими веде переговори ваша компанія, можуть бути, а можуть і не бути тими, хто винайшов це правило на 25%. Це може бути правило, накладене на них від вище.

Я бачу п'ять можливих відповідей:

Один. Переконайте свого начальника або того, хто веде переговори з клієнтом, щоб сперечатися з цього приводу. Шанси цього нічого не принесуть, але ви можете спробувати.

Два. Відмовтеся це робити. Це, ймовірно, звільнить вас, або якщо компанія погодиться з вами, призведе до втрати контракту. Це здається малопродуктивним.

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

/*
GetFoo function
Parameters:
  name: String, contains name
  num: int, the number
  add_date: date, the date added
Returns:
  foo code: int
*/
int GetFoo(String name, int num, Date add_date)

Заперечення про те, що такі коментарі є тягарем за технічне обслуговування, оскільки ви повинні постійно їх оновлювати, не є дійсним. Немає необхідності постійно їх оновлювати, оскільки жоден серйозний програміст ніколи не перегляне їх. Якщо у вас є якісь запитання з цього приводу, не забудьте уточнити всім членам команди, що марні, зайві коментарі слід ігнорувати. Якщо ви хочете знати, якими є параметри функції або що робить рядок коду, прочитайте код, не дивіться на марні коментарі.

Четверо. Якщо ви збираєтесь додавати зайві нікчемні коментарі, можливо, варто витратити час, щоб написати програму для їх генерації. Щось із інвестицій наперед, але може врятувати купу введення тексту.

Ще коли я почав займатися цим бізнесом, компанія, над якою я працювала, використовувала програму, яку рекламували як "Пишемо вашу документацію! Повна документація для кожної програми!" Система вимагала, щоб ми дали всім змінним по суті безглузді імена, а потім створили таблицю, яка містить значущу назву кожної змінної, тому в основному те, що робила "автоматична документація", замінило безглузде ім'я, яке змусило нас використовувати значущим ім'ям. Так, наприклад, - це працювало з COBOL - у вашій програмі був би рядок

MOVE IA010 TO WS124

і вони будуть генерувати рядок "документації", який сказав

COPY CUSTOMER NAME IN INPUT RECORD TO CUSTOMER-NAME IN WORKING STORAGE

У всякому разі, можна було б точно написати програму для генерування однаково нікчемної документації досить легко. Прочитайте подібний рядок

a=b+c

і генерувати коментар

// add b to c and save result in a

І т.д.

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

О, до речі, можу додати, що ви завжди можете грати в метрику.

Пригадую, одного разу роботодавець сказав, що збирається почати вимірювати продуктивність програмістів за кількістю рядків коду, які ми виробляємо на тиждень. Коли нам сказали про це на зустрічі, я сказав: Чудово! Я можу легко збільшити свою оцінку. Більше не писати

x=x+4;

Натомість я напишу:

x=x+1;
x=x+1;
x=x+1;
x=x+1;

Петлі? Забудьте про це, я копіюю і вставляю код десять разів. І т.д.

Тому тут, якщо вони збираються рахувати рядки коментарів, зробіть кожний рядок і продовжуйте ідею в наступному рядку. Якщо в коментарях є зміна того, що йдеться, не оновлюйте існуючий коментар. Поставте дату, потім скопіюйте весь текст і напишіть "Оновлено" та нову дату. Якщо клієнт сумнівається, скажіть їм, що ви вважали за потрібне підтримувати історію. І т.д.

Довільні показники здаються фактом життя в занадто багатьох проектах ...

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

Коментарі слід додати до коду та пояснити, що відбувається (а не просто повторити код!).

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

За короткий термін є нічого, що ви дійсно не можете зробити. Ідіть разом із цим.

Ви також повинні ігнорувати всі дурні ідеї, які я бачу в цій темі про пасивні агресивні протести та нерозумні жарти в коді.

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

Ні за яких обставин не слід проти цього без дозволу клієнта.

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

Мені здається, клієнт провів деякі дослідження. Він, можливо, десь читав, що код якості зазвичай містить близько 25% коментарів. Очевидно, що він піклується / турбується про технічне обслуговування далі вниз. Тепер, як він вносить цей бетон у документ про вимоги, який повинен бути прив’язаний до контракту? Це непросто. Це може бути навіть неможливо. Однак він хоче переконатися, що він отримає співвідношення своїх грошей, щоб перерахувати деякі показники якості.

Це мені зовсім не звучить дурно або смішно. Люди, які написали вимоги, швидше за все, не програмісти. Вони, можливо, мали поганий досвід з попереднім проектом. Хлопці, що їх обслуговують, скаржаться: "Нічого цього лайна не зафіксовано!". Звучить у вухах, коли вони пишуть нові вимоги до наступного проекту.

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

Зрештою, будь то 21% чи 29%, ніхто не буде байдужим. Клієнт перегляне ваші речі у якогось незалежного розробника, і він краще зрозуміє, що ви зробили.

Я зустрів багатьох програмістів, які не розуміють, як існують люди, які зараз не працюють над цим проектом.

Для них все, що вони знають, це знають усі.

Якщо хтось не знає ВСЕ, що вони зараз знають, то ці люди для них "ідіоти".

За допомогою цього стандарту ви можете змусити людей потрапляти у звичку писати коментарі.

Вони можуть писати марні коментарі 99% часу, але іноді вони можуть насправді записати одну з речей, які "ВСЕ ЗНАЄ", а хтось новий в команді може насправді не витрачати 16 годин на пошуки помилок (що хтось уже вирішив, але потім було скасовано з іншої причини), що було б очевидним із коментарем у цьому пункті коду.

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