Как я могу тактично предложить улучшения плохо продуманного кода других во время проверки?

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

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

1. Перепроверьте свою мотивацию. Если вы думаете, что код должен быть изменен, у вас должна быть возможность сформулировать причину, по которой вы думаете, что он должен быть изменен. И эта причина должна быть более конкретной, чем «я бы сделал это по-другому» или «это безобразно». Если вы не можете указать на какую-то выгоду от предложенного вами изменения, то нет смысла тратить время (или деньги) на его изменение.

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

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

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

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

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

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

Есть приятное место для повышения ценности за счет рефакторинга. Изменения должны выполнить три вещи:

• улучшить код, который может измениться
• повысить ясность
• стоить минимум усилий

Соображения:

1. Мы знаем, что чистый код дешевле писать и поддерживать, и над ним веселее работать. Ваша задача - продать эту идею людям в вашей компании. Думай как продавец, а не как высокомерный ворчун (т.е. не такой как я).
2. Вы не можете выиграть, вы можете только проиграть меньше.
3. Сосредоточьтесь на добавлении реальной ценности, а не только красоты. Мне нравится, что мой код выглядит красиво, но иногда приходится признать, что недорогие вещи важнее.
4. Хороший способ найти лучшее место - следовать принципу бойскаута - когда вы работаете над областью кода, всегда оставляйте ее в лучшей форме, чем вы ее нашли.
5. Небольшое улучшение лучше, чем отсутствие улучшения.
6. Хорошо используйте автоматизированные инструменты. Например, инструменты , которые просто чистят немного форматирования может сделать мир разницы.
7. Продавайте другие идеи, которые улучшают ясность кода. Например, модульное тестирование поощряет разложение больших методов на более мелкие.

Если код функционирует без серьезных ошибок и немалый срок (как в P & L эффектов или корпоративном PR) неизбежен, уже слишком поздно предлагать улучшения, которые требуют серьезных изменений. Даже улучшения в коде могут создавать риски для развертывания проекта. Время для улучшений было раньше в проекте, когда было больше времени, чтобы инвестировать в будущую надежность кодовой базы.

Проверка кода служит 3 целям:

1. Проверка на ошибки

2. Проверка, чтобы увидеть, где код может быть улучшен

3. Инструмент обучения для тех, кто написал код.

Оценка дизайна / качества кода, конечно, касается № 2 и № 3.

Что касается № 2:

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

  Например, «X» подход к проектированию значительно уменьшит вероятность появления ошибки Y при внесении изменений Z, и мы знаем, что этот фрагмент кода претерпевает изменения типа Z каждые 2 недели. Стоимость обработки производственных сбоев из-за ошибки Y + поиск ошибки + исправление и выпуск исправления + альтернативные издержки от невыполнения следующего набора функций - это $A, тогда как стоимость очистки кода сейчас и альтернативные издержки (например, цена доставки с опозданием или с меньшим количеством функций) равна $B. Теперь оцените - или скорее есть свой руководитель группы / менеджер - оценить $Aпротив $Bи принять решение.

  • Это поможет умной команде привести к эффективному управлению этим. Например, они примут рациональное решение, используя полную информацию

  • Это (особенно если вы это хорошо скажете) поднимет ВАШ статус - например, вы достаточно умны, чтобы видеть преимущества лучшего дизайна, И достаточно умны, чтобы не требовать этого религиозно, не взвесив бизнес-соображений.

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

Что касается № 3:

• ОЧЕНЬ четко обозначены «исправленные» ошибки / проблемы из «Это лучшая практика, и ее действительно следует исправить, ЕСЛИ мы можем сэкономить ресурсы - см. Прилагаемый анализ« за »и« против »« Улучшения конструкции (см. Материал, описанный для # 2 выше) против » Это общие рекомендации, которые, я думаю, помогут вам улучшить надежность кода, чтобы вам было легче поддерживать его в коде «необязательные изменения». Пожалуйста, обратите внимание на формулировку - речь идет не о том, чтобы «сделать ваш код похожим на то, что я хочу», а о том, что «если вы сделаете это, ВЫ получите преимущества a, b, c». Тон и подход имеют значение.

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

Они должны увидеть ценность, прежде чем делать дополнительную работу.

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

Я также всегда включаю причину.

« Я бы извлек этот блок в метод из- за читабельности».

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

Я пытаюсь установить общий язык по причинам; удобочитаемость, СУХОЙ, SRP и т. д.

Я также создал презентацию «Чистый код и рефакторинг», объясняющую почему и показывающую, как, которую я провел своим коллегам. До сих пор я держал его три раза, и одна из консультантов, которую мы используем, попросила меня снова подержать их.

Но некоторые люди все равно не будут слушать. Тогда я остаюсь с растяжкой. Я ведущий дизайнер. Качество кода - моя ответственность. Это изменение не пройдет через мои часы в их текущем состоянии.

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

О, и я недавно предложил купить ланч первому в моей команде, который представил нетривиальное изменение, к которому у меня не было никаких комментариев. (Эй, ты тоже должен повеселиться. :-)

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

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

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

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

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

или же

Эй, босс, мы готовы выпустить. Если нам когда-нибудь понадобится добавить функцию X, это может занять пару дополнительных дней.

Если бы вы сказали один из них, ваш босс, скорее всего, сказал бы:

Кто сказал что-нибудь о функции X?

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

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

Вот некоторые принципы, которые я считаю полезными:

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

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

Не забудьте сделать положительные комментарии. Краткое "приятно!" или "аккуратный трюк!" может сделать день младшего или незащищенного программиста.

Предположим, что другой человек умен, но иногда небрежен. Не говорите: «Как вы ожидаете, что вызывающая сторона получит возвращаемое значение, если вы на самом деле не возвращаете его ?!» Скажите: «Похоже, вы забыли ответное заявление». Помните, что вы написали ужасный код в первые дни. Как кто-то однажды сказал: «Если вам не стыдно за свой код год назад, вы не учитесь».

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

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

Интересно, будет ли лучше ...

или же

Имеет ли смысл ...

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

«Да, это хорошая идея, потому что < ваша очевидная причина здесь >».

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

Интересно, есть ли способ ... <утверждение общего значения здесь>

Это только для того, чтобы иметь дело с действительно обидчивыми людьми - с большинством моих сверстников, я просто позволю им иметь это!

Обзоры кода не всегда направлены на улучшение.

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

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

Ваш вопрос «Как проверить код плохо спроектированного кода?»:

Ответ ИМО прост. Поговорите о ДИЗАЙНЕ кода и о том, как дизайн имеет недостатки или не соответствует требованиям. Если вы укажете на некорректный дизайн или «не соответствует требованиям», то разработчик будет вынужден изменить свой код, потому что он не выполняет то, что ему нужно.

Если код «функционально достаточен» и / или «соответствует спецификации» и / или «соответствует требованиям»:

Если вы являетесь партнером этого разработчика, у вас нет прямых полномочий, которые позволили бы вам «сказать ему» о внесении изменений.

Есть несколько вариантов:

1. Вы должны использовать свое личное «влияние» (форма «власти», которая является косвенной) и / или вашу способность быть «убедительным»
2. Примите участие в работе группы «Процесс обработки кода» вашей организации и начните делать обслуживание кода более приоритетным.
3. Укуси пулю и научись читать дрянной код быстрее / быстрее, чтобы не зацикливаться (кажется, что ты продолжаешь зависать или тормозить, когда сталкиваешься с дрянным кодом) с дерьмовым кодом.
   • Это также сделает вас более сильным программистом.
   • И это позволит вам исправить дрянной код, когда вы работаете над дрянным кодом.
   • И это также позволит вам работать над большим количеством проектов, потому что во многих проектах есть дрянной код, который функционален ... но много дрянного кода.
4. Подавать пример. Сделайте свой код лучше ... но не пытайтесь быть перфекционистом.
   • Потому что тогда вы станете «медленным парнем, который не может уложиться в сроки, всегда критикует и думает, что он лучше всех».

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

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

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

Как только вы установите барьеры между компонентами, сфокусируйтесь на компонентах, которые могут вызвать серьезные проблемы.

Повторяйте до крайнего срока или пока система не станет «идеальной».

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

Один из способов, которым я следую,

1. будет оптимальным, если мы сделаем это таким образом.
2. Написание этого таким образом заставит его работать быстрее.
3. Ваш код будет намного более читабельным, если вы сделаете «это», «это» и «это»

Такие комментарии будут приняты всерьез, даже если ваши сроки приближаются. И, вероятно, будет реализован в следующем цикле разработки.

Проверка кода должна быть интегрирована с культурой и циклом разработки для работы. Маловероятно, что планирование большого обзора кода в конце разработки функции X сработает. Прежде всего, вносить изменения будет сложнее, и кто-то, вероятно, будет смущен - создавая сопротивление деятельности.

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

Повысить качество кода отзывов.

Помимо качества проверяемого кода, существует такая вещь, как качество самого обзора кода:

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

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

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

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

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

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

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

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

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

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

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

Но, пожалуйста, постарайтесь не оказаться в этом сценарии в первую очередь!