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

184

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

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

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

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

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

Mahbubur R Aaman
источник
109
Комментирование ради комментариев не делает код лучше. Если код понятен (в том числе почему) без комментариев, тогда хорошо, если нет комментариев.
Мартин Йорк
63
О да, и когда сложность некоторого фрагмента кода увеличивается в три раза, чтобы решить условие гонки или тупик, не комментируйте это! Пусть люди решают загадку, почему код должен быть таким, какой он есть, и почему он ломается таинственными способами, если они вносят экспериментальные изменения. Каждый должен быть шахматным гроссмейстером параллелизма ...
Каз
12
@ Kaz Sarcasm (я надеюсь) плохо переводит текст.
deworde
10
@ deworde & artjom - да, это сарказм. нет, это не так ясно, как могло бы, но это явно сарказм.
17
следуя принципу Дейла Карнеги, вы должны попытаться понять, почему он не хочет комментировать ... вы упомянули, что он не хочет откладывать проект ... так что вы можете сказать ему, что если он не прокомментирует других, то не будет в состоянии понять код и это еще больше задержит проект .. это определенно должно помочь ..
Anirudha

Ответы:

431

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

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

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

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

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

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

tdammers
источник
269
+1 за «не жалуйтесь на пропущенные комментарии: жалуйтесь на нечитаемый код».
Г-н Махбубур Рахман
4
Что, если ответ на любой вопрос о коде будет таким: «Что вы сделали, чтобы понять его?»
Сол
40
+1: Нажатие на читаемые имена функций может иметь дополнительные преимущества ... В Code Review: «Не могу понять, что делает xg_jkhsfkasq». «О, это очищает основной буфер подачи, теперь я могу освободить?» «Конечно, но мне не терпится утвердить его, пока вы не переименуете функцию flush_primary_buffer» «Ах, но он также очищает основной кеш, так что имя будет вводить в заблуждение» «ЭТО ЧТО? Не очищайте этот кеш, оно Вы остановите систему! Пока вы меняете эту логику, не могли бы вы переименовать эту функцию? "
deworde
18
Я бы беспокоился о том, чтобы создать впечатление, что я не могу прочитать код. Нетехнический менеджер может просто заметить, что я постоянно обращаюсь к «Бобу» за помощью, потому что код Боба слишком сложен для меня. Это означало бы, что Боб - «продвинутый» разработчик, и я не готов работать на его уровне.
Роб П.
5
@Rob P. Я вижу страх, но если вы не можете прочитать код, и ожидается, что вы будете поддерживать код, то код написан не очень хорошо, или вы не знаете достаточно. Если вы не знаете достаточно, вам нужно спросить. Если в результате запроса выясняется, что код просто трудно прочитать, нажмите для его исправления. Уловка была бы, если вы идете по пути социальной инженерии, чтобы смешать его, идет ли Боб к вашему столу или вы идете к нему, и быть очень активным в отношении указания на вещи. В конце концов,
нетехнический
114

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

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

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

Док Браун
источник
5
+1 это единственный способ действительно внедрить изменения в коллегу, которого я нашел, на самом деле сидеть с ними и просматривать / рефакторинг вместе с ними. Если вы не можете отказать в проверке кода, это может быть сложно. Иногда, когда вы находитесь на среднем уровне, вам просто нужно ставить вопросы пожилым людям, и если они не слушают, высовывайте нос, пока вы не достигнете совершеннолетия и не наложите вето на такой мусор
Джимми Хоффа
1
Обзоры кода и парное программирование - лучший способ улучшить общий уровень разработчиков в команде. Речь идет о разделении знаний и навыков внутри команды. Без этого вы заставляете разработчиков учиться трудным путем и предполагаете, что они окончательно закончили колледж. Общий недостаток этой практики в отрасли, вероятно, является причиной того, что существует так много разработчиков с более чем 10-летним опытом, которые не могут писать хорошо читаемый, хорошо организованный код.
Мартин Браун
27

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

Earlz
источник
2
+1 - если вам нужно задать вопрос о какой-либо части кода, то эта часть либо нуждается в комментарии или рефакторинге, чтобы в будущем этот вопрос не задавался кем-то другим.
Данк
+1 Также удивил, что отзывы о кодах и рецензиях так низки в ответах. Реализация проверок кода на уровне команды (чтобы не выбирать отдельных) может помочь решить проблему (и, возможно, другие, о которых вы даже не подозреваете :). В крайнем случае вы могли бы внедрить политику «без соло-толчка», согласно которой вам не разрешено толкать, если ваши изменения не были рассмотрены другим членом команды.
Крис Ли
@ChrisLee в моей политике проверки кода компании технически не применяется, но есть политика, согласно которой, прежде чем история может быть помечена как готовая к тестированию, она должна быть проверена кодом, независимо от того, кто занимался разработкой. Это довольно интересно, когда нужно проверять код, когда технический директор
регистрирует это,
18

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

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

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

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

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

Фрэнк
источник
+1 за обсуждение фактической прибыли от комментариев. Комментарии предназначены для повышения ценности исходного кода.
Sparky
1
Re: «этот вид принуждения, скорее всего, приведет к ужасным комментариям». Если вы не комментируете при кодировании, то обратное заполнение комментариев после выполнения кода почти всегда приводит к ужасным комментариям, независимо от того, верите вы в них или нет. Когда вы кодируете, это время, когда вы точно знаете, ПОЧЕМУ вы делаете что-то определенным образом. Это время, чтобы сообщить другим. Если вы прокомментируете после того, как закончите, скорее всего, вы даже не вспомните, о чем думали, когда писали код, поэтому вы склонны добавлять бесполезный комментарий только ради комментариев.
Данк
3
всегда была проблема с подходом этой книги. Комментарии могут быть v. Полезны при объяснении бизнес-процесса / логики (или почему), что никакое количество чистого кода не может.
Бхарал
В то время как комментарии в коде не были бы необходимы, должно быть по крайней мере описание метода, такое как Javadoc
Дунайский моряк
2
Чистый кодекс - достойная книга, но ее не следует воспринимать как Евангелие. Вы должны применять здравый смысл и решить для себя, что работает. Я не согласен с рекомендациями по комментариям, потому что языки программирования ориентированы на то, чтобы выразить причину проблемы со скудным отношением к причине. Я писал код для Google Shopping, который добавляет код страны к SKU продукта. Совершенно очевидно, что делает код, но если вы не знаете, что можете использовать один и тот же код продукта только один раз, даже на разных рынках, вы не узнаете, почему я это делал. Комментарий, который я добавил, проясняет это.
GordonM
10

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

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

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

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

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

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

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

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

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

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

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

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

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

оборота Дэнни Таппени
источник
4

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

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

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

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

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

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

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

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

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

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

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

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

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

Евгений Якимович
источник
Вы можете написать код, который не нуждается в комментариях только для развлечения. Это действительно может быть отличным упражнением, но не в том случае, если вам нужно вернуться к коду и действительно ничего не изменить, потому что вы не будете знать, почему эта функция работает так, как она работает, возможно, был какой-то клиент, который хотел этого. Конечно, вы можете быть в этом, может быть, 1% проекта, который задокументирован и обоснован вне проекта, но даже тогда есть решения, которые вы принимаете во время кодирования, которые не возвращаются к документации. И, честно говоря ... Кто читает документацию, которой нет в коде. Конечно, не программисты ;-P.
Nux
1
Хороший инженер заботится обо всей системе (включая документацию, не генерируемую кодом) - но здесь мы, конечно, занимаемся кодированием ума в целом. Я хочу сказать, что отсутствие идентификаторов в коде с именами foo , bar , tmpSomething2 и IamJustTooSmartAssToCare уже улучшает ситуация и уменьшает общую необходимость объяснить, что такое код и что он делает. Код должен быть написан с «режимом мышления», как хорошо разработанный API, который читается, понимается, используется и поддерживается людьми. Слишком много комментариев в коде, которые иначе трудно понять, - очень плохой знак!
Евгений Якимович
Кстати, программирование / кодирование любого типа предметно-ориентированной логики в форме HACK или «временного» исправления ошибки фактически приводит к появлению «странных HACK» - как только вы их втисните в черный ящик - ожидайте, что они терпеть неудачу и отстреливаться. Это может быть оправдано сроками в проектах «реального мира» и т. Д. но на самом деле это просто дешевое программное обеспечение, которое требует перестройки логики предметной области (или, возможно, поиска новой работы).
Евгений Якимович
Я согласен с тем, что читабельность важна, но я не согласен с тем, что вы, кажется, говорите: «если вы сделаете читабельность приоритетом, вам не понадобятся комментарии». Это просто не соответствует действительности. Там было сделано это. Рассуждение о том, что вы делаете, происходит не просто от именования переменных таким способом, который имеет смысл. Сделайте это, конечно, но также добавьте причину в комментариях (даже если это в форме номера ошибки / требования / истории в некоторой внешней системе). Это то, что я говорю.
Nux
«если вы сделаете читабельность приоритетом, вам не понадобятся комментарии» - да, это именно то, что я говорю (и я знаю, что это нелегко достичь). Кстати, у вас есть ситуации, когда ведение полной истории фиксации (контроля версий) недостаточно для отражения "ошибки / требования / номера истории"? Я практикую довольно длительные коммиты - работает для меня и позволяет сохранить код пустым от истории разработки .. делает его менее органично выращенным.
Евгений Якимович
3

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

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

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

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

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

Если они представляют собой комментарии к документации на уровне 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) Комментарии загромождают код и очень редко добавляют какую-либо ценность.

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

Paul
источник
4
Это просто глупо. Я надеюсь, что никто не верит, что такой плохой стиль комментирования полезен. Но вы искренне верите, что комментарии никогда не должны использоваться?
JMK
1
Да, это глупое предположение, если код невероятно читаемый, я мог бы понять немного комментариев, но, увидев комментарии, следует сказать, почему метод делает то, что он есть, и где он будет использоваться, когда вы доберетесь до нескольких классов, которые действительно есть. нет причин для комментариев, они помогают всем.
DBlackborough
3
Важно помнить, что, хотя сейчас все для вас имеет смысл, кто-то другой должен будет поддерживать ваш код в течение 3 лет. Не облажайся.
xaxxon
4
@xaxxon Не говоря уже о том, что яблоки, даже если этот человек может быть вами.
пушистый
3
@mehaase - Не что, не как, но почему это самая важная причина для добавления комментариев к коду.
Хенк Лангевельд
1

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

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

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

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

Brendan
источник
1

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

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

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

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

оборота LJ2
источник
Когда комната, заполненная людьми, начнет смеяться над вашим нечитаемым кодом, вы начнете лучше кодировать и комментировать. :) Я большой сторонник обзоров кода.
Эвик Джеймс
1
Заставлять людей смеяться над кодом перед другими коллегами - не
лучший
1
Если люди, занимающиеся анализом кода, скорее смеются, чем конструктивны, им нужно столько же тренироваться, сколько и разработчику, который не может написать читаемый код. Критика, которая является конструктивной, а не уничижительной, является одним из социальных навыков, которые мне часто не хватает разработчикам.
Мартин Браун
1

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

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

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

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

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

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

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

Билл
источник
0

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

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

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

mouviciel
источник
6
Нет, таким образом, разработчики должны написать некоторые комментарии. Их полезность уменьшается с давлением , чтобы написать их, часто опускаясь ниже нуля в активно вредном регионе (недействительный комментарий это хуже , чем без комментариев) , если политика сильно толкнул.
Ян Худек
1
@JanHudec - я согласен с тобой. Вот почему некоторый контроль должен быть установлен. Автоматическая генерация гарантирует, что, например, аргументы функции в коде такие же, как в комментариях. Более того, наличие одного PDF-файла вместо каталога исходных файлов делает документацию более читабельной (т.е. более читаемой) большим количеством людей.
Mouviciel
2
Ну нет, это не так. Как вы собираетесь заметить в .pdf, что код на самом деле немного отличается от описания?
Ян Худек
1
Может быть, мое мнение искажено моим доменом, критически важным программным обеспечением, где все проверяется, контролируется, проверяется, тестируется дважды, три или четыре раза. Автоматическая генерация документации не устраняет несоответствия, но помогает уменьшить их.
mouviciel
Да, вы сильно предвзяты. В подобных областях это имеет смысл, в большинстве модульных тестов достаточно для обеспечения качества, и документирование каждой последней функции будет пустой тратой времени.
Ян Худек
0

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

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

reinierpost
источник
0

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

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

   var str1:String="" //not uderstandable
   var strSearchPattern:String="" //uderstandable
М.С.Наяк
источник
0

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

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

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

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

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

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

Билл К
источник
0

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

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

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

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

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

GordonM
источник
-1

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

Абхишек Галоут
источник
12
Я просто едва избежал кнопки -1 на этом. Большая часть кода, который я пишу, имеет очень мало комментариев. Я не думаю, что люди жаловались, что это не понятно, по крайней мере, в последние несколько лет. За очень немногими исключениями, если код нуждается в комментариях для понимания , тогда он не нуждается в комментариях, он нуждается в улучшении для ясности. (Конечно, вы должны принять базовое понимание синтаксиса языка. Такие вещи, как в C ++, не выходят из-под контроля, просто избегая использования, reinterpret_cast<>()потому что люди могут найти это запутанным; в C #, если ??делает то, что вам нужно, используйте это и т. д.)
CVn
2
@ MichaelKjörling: Это может сильно зависеть от того, какой код вы пишете. Если ваш код зависит от необычно известных характеристик языка или API, или вы сделали что-то нелогичным, чтобы избежать неясной ошибки, на поиск которой у вас ушли часы, было бы намного эффективнее комментировать это (возможно, включая ссылку на статью), чем пытаться сделать код «понятным» об этой исходной информации без комментариев.
LarsH
@ MichaelKjörling: Я особенно мотивирован сказать это сегодня, потому что я боролся в течение прошлого месяца с глубоким ГИС API. Средства API сложны и не очень тщательно документированы. Мы постоянно сталкиваемся с сюрпризами, некоторые из которых отодвигают нас на задний план. Ожидать, что кому-то другому (или мне через 6 месяцев) придется заново открывать эти самородки, чтобы эффективно работать с нашим кодом, было бы огромной тратой времени этого человека. И эти секреты, как правило, не могут быть задокументированы без комментариев "улучшение для ясности".
LarsH
@LarsH Это, вероятно, можно отнести к числу «очень немногих исключений», которые я упомянул в своем комментарии. Я не против комментировать, где это на самом деле добавляет ценность ; но не количество комментариев делает код легким или трудным для чтения. Тем не менее, с API, я был бы более склонен документировать эти причуды в другом месте; скажем, в вики или подобном. Возможно также добавить ссылку на соответствующую страницу рядом с каждым использованием. Таким образом, вам не нужно искать какое-то другое место, где используется именно эта особенность API, когда код не работает так, как вы ожидаете с первой попытки.
CVN
@ MichaelKjörling: согласился в целом. Являются ли эти исключения редкими или нет, зависит от области, для которой вы программируете, и API, которые вы должны использовать. Ссылки / ссылки хороши для заметок, которые применяются в целом, а не только к текущей ситуации. Никто не хочет диссертации в самом коде.
LarsH
-1

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

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

Арх
источник
1
Этот подход более приятен, чтобы заставить программиста бросить курить, а не обучать их правильному способу выполнения действий.
Мартин Браун
-1

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

agilob
источник
-1

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

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

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

У меня есть привычка делать свои комментарии самой очевидной вещью в моей 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 */

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

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

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

Джонатан
источник
-2

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

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

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

М. Дадли
источник
1
Я бы сказал, что более чистый код / ​​рефакторинг кода для большей читабельности демонстрирует большие изменения, чем добавление в код больших объемов комментариев.
Макото
Может кто-нибудь объяснить мне, что им не нравится в моей идее ...?
М. Дадли
-6

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

Питер
источник
11
"Авто коммент"? Так вот, откуда все эти комментарии "прирост i на 1"? Какая IDE это делает (чтобы я мог избежать работы, где она используется)?
CVn
Я пытался отредактировать это как-то читабельное, но я не уверен, должно ли слово сначала иметь запятую перед или после него. Фраза комментирует сначала или сначала говорит в каждом методе ?
TRiG