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

Один из членов моей команды постоянно избегает комментариев в своем коде.

Его код не самодокументирован, и другим программистам трудно понять его код.

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

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

На этой ноте я не прав, чтобы сосредоточиться на комментариях к коду или это свидетельствует о более крупной проблеме, которую следует решить?

Комментарии сами по себе не улучшают код, и простое нажатие кнопки «больше комментариев», скорее всего, даст вам немного больше, чем /* increment i by 1 */стиль комментариев.

Так что спросите себя, зачем вам эти комментарии. «Это лучшая практика» не считается аргументом, если вы не понимаете, почему.

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

Так что не жалуйтесь на пропущенные комментарии: жалуйтесь на нечитаемый код. Или, что еще лучше, не жалуйтесь, просто продолжайте задавать вопросы о коде. Для чего-то, что вы не понимаете, спросите человека, который написал это. Вы должны делать это в любом случае; с нечитаемым кодом, вы просто будете задавать больше вопросов. И если вы позже вернетесь к коду кода и не уверены, что правильно помните, что он делает, задайте тот же вопрос еще раз.

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

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

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

То, что никогда не работает, это «говорить им, чтобы они добавляли больше комментариев». Это не увеличит ни их самодисциплину, ни опыт. ИМХО, единственное, что может сработать - это частые обзоры кода и рефакторинг. Когда разработчик выполнил задачу, позвольте ему / ей объяснить любые части кода, которые вы не понимаете. Немедленно рефакторинг или документирование кода таким образом, чтобы вы оба поняли 6 месяцев спустя.

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

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

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

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

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

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

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

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

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

1. Он стесняется своего выбора кода / дизайна и не хочет выкладывать их в прозе. (Обзоры кода могут быть полезны для укрепления чьей-то уверенности в себе, а также для разрушения.)
2. Он работает очень линейно и много не думает. Комментирование болезненно, потому что вынуждает его выгружать непосредственный код, который он собирался написать, из своей рабочей памяти, чтобы составить свое намерение другим способом. (Если это правда, комментирование становится очень важным для его качества кода.)
3. Исторически люди не понимают его комментарии.

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

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

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

Мы используем печь, и нам это нравится. У нас есть политика, согласно которой каждый набор изменений должен быть проверен (хотя мы позволяем разработчикам самим создавать / утверждать проверки по тегам и слияниям без конфликтов (хотя большинство из нас используют rebaseif); таким образом мы можем быстро определять наборы изменений без проверок).

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

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

При использовании программного обеспечения, такого как Kiln, не пропускаются никакие изменения. Все в моей команде разработчиков так предпочитают. Программное обеспечение для проверки кода оказало огромное влияние как на качество нашего кода, так и на качество приложения :-)

Разработчикам легко защищаться с отклоненными отзывами при первом представлении программного обеспечения, но, по моему опыту, им не нужно много времени, чтобы понять, что дела обстоят лучше, и принять это :-)

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

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

Почему комментарии?

Хотя комментарии к коду являются формой встроенной документации, в языках высокого класса существует множество способов избежать излишнего «чрезмерно документированного» программирования (значимого кода) с использованием элементов самого языка. Также плохая идея превращать код в списки из учебника по программированию, где отдельные утверждения буквально объясняются почти тавтологическим образом (обратите внимание на пример "/ * приращение i на 1 * /" в уже предоставленных ответах), делая такие комментарии актуальными только для программистов, неопытных с языком.

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

Читаемость кода! = Комментарии кода

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

С другой стороны, читаемая программа = код + документация может содержать несколько допустимых разделов комментариев, например, чтобы облегчить создание документации «комментарии к API».

Следуйте стандартам стиля кода

Как ни странно, вопрос не в том, зачем комментировать код, а в командной работе - как создать код в высоко синхронизированном стиле (который все остальные могут читать / понимать). Соблюдаете ли вы какие-либо стандарты стиля кода в вашей компании? Его главная цель - избежать написания кода, который требует рефакторинга, является слишком «личным» и «субъективно» неоднозначным. Таким образом, я думаю, если кто-то видит необходимость в использовании стиля кода, есть целый ряд инструментов, как правильно его реализовать - начиная с обучения людей и заканчивая автоматизацией для контроля качества кода (многочисленные ссылки и т. Д.) И (ревизия). интегрированные системы контроля).

Станьте евангелистом по читабельности кода

Если вы согласны, что код читается чаще, чем написано. Если для вас важно ясное выражение идей и ясное мышление, независимо от того, какой язык используется для общения (математика, машинный код или древнеанглийский) .. Если ваша миссия состоит в том, чтобы искоренить унылый и уродливый способ альтернативного мышления .. (извините последний - из другого "манифеста") .. задайте вопросы, инициируйте дискуссии, начните распространять книги, заставляющие задуматься о чистке кода (вероятно, не только что-то похожее на шаблоны проектирования Бека, но больше как уже упоминавшиеся Р. К. Мартином ), которые решают неоднозначность в программировании. Далее идет ключевой отрывок ключевых идей (цитата из книги О'Рейли о читабельности)

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

Вырезая «комментирование», у одного все еще остается много (я думаю, написание кода, который не нуждается в комментариях, является одним из отличных упражнений!). Называние семантически значимых идентификаторов - хорошее начало. Далее, структурирование вашего кода путем группировки логически связанных операций в функции и классы. И так далее. Лучший программист - лучший писатель (конечно, с учетом других технических навыков).

я ошибаюсь, сосредотачиваясь на комментариях к коду или это свидетельствует о более серьезной проблеме, которую следует решить?

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

Так как это сделать? Рекомендации Дока Брауна по поводу обзоров / рефакторинга - хорошая идея. Я считаю, что парное программирование еще более эффективно, но его также может быть значительно сложнее реализовать.

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

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

В большинстве случаев, с которыми я сталкиваюсь, комментарии являются злыми. Я бы порекомендовал прочитать главу «Чистый код» Роберта Мартина с комментариями к коду, чтобы понять, почему.

Комментарии вредят вашему коду несколькими способами:

1) Их сложно поддерживать. При рефакторинге вам придется потратить дополнительную работу; если вы измените логику, описанную в комментарии, вам также необходимо отредактировать комментарий.

2) Они часто лгут. Вы не можете доверять комментариям и должны читать код вместо этого. В связи с этим возникает вопрос: зачем вам вообще нужны комментарии?

// this method returns the sum of 'a' and 'b'
public int GetHash(int a, int b)
{
    //the calculation of the hash
    int result = a*b;
}

(Хеш - не сумма, а произведение.)

3) Комментарии загромождают код и очень редко добавляют какую-либо ценность.

Мое решение: вместо того, чтобы добавлять больше комментариев, постарайтесь вообще от них избавиться!

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

В этом случае, если нехватка комментариев является проблемой, то человек, который недостаточно комментирует свой код, будет тратить много времени на объяснение того, что он сделал; и (если они умные) начнут добавлять комментарии, чтобы не тратить время на все эти объяснения.

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

Главным образом, поощряя членов команды спрашивать друг друга о объяснениях, вы создаете самобалансирующуюся систему; где разные члены команды «автоматически подстраиваются» друг к другу.

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

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

РЕДАКТИРОВАТЬ: Я не уверен, почему кто-то будет отклонять мое предложение - возможно, я принимал как должное, что преимущества проверки кода будут общеизвестны ... пожалуйста, смотрите эту ветку для анализа практики сообщества:

Является ли проверка кода хорошей практикой?

Принимая во внимание часто крайние взгляды на комментарии, я не решаюсь взвесить. Это, как говорится ...

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

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

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

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

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

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

Многие проекты требуют кодовой документации: интерфейсный документ, проектная документация, ...

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

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

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

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

Если вы следуете хорошему стандарту кодирования, комментарии будут минимальными. соглашения об именах важны. Имена методов и имена переменных должны описывать их роль.

Мой TL предлагает мне использовать меньше комментариев. он хочет, чтобы мой код был понятным и информативным. простой пример: имя переменной для типа строки, используемой для шаблона поиска

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable

Люблю ответы на обзоры кода, но, возможно, мой процесс тоже немного поможет.

Я люблю комментарии, но я почти никогда не добавляю их в код с первого прохода. Может быть, это просто мой стиль, но я буду использовать один и тот же фрагмент кода от 3 до 5 раз во время разработки (рефакторинг, написание тестов и т. Д.).

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

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

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

Серьезно подумайте о том, чтобы настаивать на этом как на части вашего «Командного контракта» (и, безусловно, создайте контракт, если у вас его нет) - таким образом, все с ним согласились, и вы где-то его повесили на стену, чтобы не было Т любой вопрос о том, что вы согласились сделать.

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

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

Нет лучшего учителя, чем суровый опыт!

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

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

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

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

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

В одном из моих прошлых проектов отсутствовали десятки комментариев (алгоритм, результаты или какой-то базовый JavaDoc), поэтому я просто решил сделать для него 130 вопросов, отправляя по электронной почте уведомление о каждой проблеме каждые 4 дня. После 3 недель у него было 280 вопросов, затем он решил написать комментарии.

Комментарии имеют одну цель и только одну цель:

Почему этот код делает это?

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

У меня есть привычка делать свои комментарии самой очевидной вещью в моей IDE. Они выделены белым текстом на зеленом фоне. На самом деле привлечь ваше внимание.

Это потому, что код объясняет, что что- то делает, и комментарии для того, почему он это делает. Я не могу подчеркнуть это достаточно.

Хороший пример комментария:

/* Must instantiate clsUser before trying to encrypt a password because the code to 
   encrypt passwords only uses strong encryption if that module is loaded. */

Плохой пример:

/* instantiate clsUser */

Если вы используете комментарии в качестве «разделов» кода: разделите ваш гигантский метод на более мелкие полезные именованные функции и удалите комментарии.

Если вы говорите о том, что вы делаете, в следующей строке: сделайте код понятным и удалите комментарий.

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

Чтобы дополнить ответы здесь, я мог бы добавить: «Если вы хотите, чтобы все было сделано правильно, вы должны сделать это сами».

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

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

Просто: если сотрудник не комментирует, попросите его нажать shift+alt+jдля автоматического комментирования в каждом методе одновременно с вводом кода. пожалуйста, сделайте пересмотр кода, чтобы избежать этих проблем.