Мой клиент хочет 25% комментариев в моем текущем проекте, как реагировать? [закрыто]

младший разработчик здесь.

В настоящее время я работаю один над веб-приложением для крупного клиента моей компании. Я начал в прошлом месяце. Клиент хочет по крайней мере 25% комментариев в каждом из своих программных проектов.

Я проверил код предыдущих приложений и вот мои наблюдения:

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

• все переменные прокомментированы с их именами // nameOfCustomer public String nameOfCustomer

• все получатели и установщики комментируются

• очень мало полезных комментариев

Похоже, что разработчики просто размещают как можно больше комментариев, чтобы достичь порога в 25%, независимо от качества и полезности. Моя компания говорит мне, что «мы делаем это так, как хочет клиент».

Я не говорил напрямую с клиентом об этом. Вот мои аргументы до сих пор:

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

Что вы посоветуете по этому вопросу? Как мне справиться с ситуацией?

Все остальные ответы и комментарии здесь действительно заставили меня задуматься, потому что они так противоречат моей первой реакции и так противоречат позиции, свидетелем которой я был в своих коллегах. Поэтому я хотел бы описать альтернативный подход, хотя бы ради того, чтобы быть несогласным голосом .

Руководящий принцип этого ответа: «Восхищение клиента». Удовлетворение клиента означает не просто удовлетворение его ожиданий; это означает понимание их запросов настолько глубоко, что вы сможете интерпретировать то, что они говорят, так, как они это имеют в виду, и поставлять сверх того, что они просят. Другие ответы, похоже, руководствуются принципом злонамеренного соответствия, который я нахожу отвратительным; и кроме того, сомнительная деловая практика, поскольку это плохой способ получить постоянных клиентов.

Для меня, когда я слышу, как клиент говорит: «Я хочу 25% комментариев», это начало диалога. Для меня очевидно, что здесь подразумевается «Я хочу много описательного текста, чтобы новички в этой кодовой базе могли быстро начать работу», а не «Я хочу, чтобы вы добавили случайность в определенной синтаксической категории», как другие ответы. Похоже, что беру это. И я бы отнесся к этой просьбе серьезно и намеревался написать много описательных, полезных комментариев, приведя новичка к структуре кода, указав на неожиданные инженерные решения и изложив их обоснование, а также на английском языке высокого уровня. описания сложных разделов кода (даже если они не имеют никаких сюрпризов). Это намерение и понимание является отправной точкойобсуждения - это еще до того, как мы начнем говорить. Для меня смысл запроса настолько ясен, что он даже не нуждается в этом разъяснении; но если вам неясно, вы должны, конечно, проверить их!

Хорошо, так, куда идет диалог, если это отправная точка? Следующая часть диалога выглядит так:

1. Я ожидаю, что это будет серьезным дополнительным усилием, возможно, на втором этапе проекта, который выходит за рамки производства инструмента, над которым они работают. Это может быть несколько минут обсуждения, чтобы обсудить этот процесс и почему это дополнительная работа, но я собираюсь опустить ее здесь, потому что, как профессиональный программист, я ожидаю, что вы знаете, как трудно делать хорошие комментарии.
2. «Серьезные дополнительные усилия» означают, что нам может потребоваться более длительный бюджет и больший денежный бюджет; или нам может потребоваться уменьшить бюджет функций; или женам может понадобиться компромисс в отношении качества и количества комментариев. Эта часть будет чем-то вроде переговоров. Но, по моему мнению, вы должны быть в курсе затрат на выполнение этой дополнительной работы и убедиться, что это настолько важная функция для клиента, что он готов взять на себя эти расходы. И если они есть - отлично! Вы получаете дополнительное время и деньги, а они получают качественные комментарии. Все побеждают. И если выясняется, что функция комментирования не так важна для них, что они готовы потерять способность трясти виджеты или хотят, чтобы крайний срок сдвинулся до позднего Грануария, 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-арт (или код Doxygen, который генерирует более приятные вещи при рендеринге). Я, конечно, не знаю, о чем идет речь в вашем проекте, но я полагаю, что вы можете сделать это без каких-либо фиктивных комментариев (кроме шаблона доксигенации) и получить что-то близкое к 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

И т.п.

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

О, кстати, могу ли я добавить, что вы всегда можете сыграть в метрику.

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

x=x+4;

Вместо этого я напишу:

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

Loops? Забудьте об этом, я скопирую и вставлю код десять раз. И т.п.

Итак, здесь, если они собираются считать строки комментариев, сделайте каждую строку короткой и продолжите идею на следующей строке. Если в комментариях есть изменения, не обновляйте существующий комментарий. Поместите дату, затем скопируйте весь текст и напишите «Обновлено» и новую дату. Если клиент спрашивает об этом, скажите им, что вы думали, что необходимо сохранить историю. И т. Д.

Произвольные метрики кажутся фактом жизни в слишком многих проектах ...

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

Комментарии должны добавить к коду и объяснить, что происходит (а не просто повторить код!).

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

В краткосрочной перспективе действительно ничего не поделаешь. Идите вместе с этим.

Вы также должны игнорировать все глупые идеи, которые я вижу в этой теме о пассивных агрессивных протестах и ​​глупых шутках в коде.

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

Ни при каких обстоятельствах вы не должны идти против этого без разрешения клиента.

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

Мне кажется, клиент провел какое-то исследование. Возможно, он где-то читал, что качественный код обычно содержит около 25% комментариев. Очевидно, он заботится / заботится о техническом обслуживании в будущем. Теперь, как он делает это конкретным в документе требований, который должен быть привязан к контракту? Это не легко. Это может быть даже невозможно. Тем не менее, он хочет убедиться, что он получит ценность за свои деньги, поэтому он перечисляет некоторые качественные показатели.

Это не звучит глупо или смешно для меня вообще. Люди, которые написали требования, скорее всего, не программисты. Возможно, у них был неудачный опыт с более ранним проектом. Ребята из их службы жалуются: «Ничего из этого дерьма не задокументировано!». Это звон в ушах, поскольку они пишут новые требования для следующего проекта.

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

В конце концов, будь то 21% или 29%, никто не будет заботиться. Клиент рассмотрит ваши материалы независимым разработчиком, и он лучше поймет, что вы сделали.

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

Для них все, что они знают, известно всем.

Если кто-то не знает ВСЕ, что он знает в настоящее время, то эти люди для них "идиоты".

С помощью этого стандарта вы можете заставить людей привыкнуть писать комментарии.

Они могут писать бесполезные комментарии в 99% случаев, но иногда они могут фактически записать одну из вещей, которые «ВСЕ ЗНАЮТ», и кто-то новый в команде может фактически не тратить 16 часов на поиск ошибки (которую кто-то уже решил, но затем был отменен по другой причине), что было бы очевидно с комментарием на тот момент в коде.

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