Мой коллега считает, что любое использование комментариев в коде (т. Е. Не метод стиля javadoc или комментарии класса) является запахом кода . Как вы думаете?
comments
anti-patterns
Fishtoaster
источник
источник
Ответы:
Только если комментарий описывает, что делает код.
Если бы я хотел знать, что происходит в методе или блоке, я бы прочитал код. В любом случае, я надеюсь, что все разработчики, работающие над данным проектом, по крайней мере достаточно знакомы с языком разработки, чтобы читать то, что написано, и понимать, что он делает.
В некоторых случаях экстремальной оптимизации вы можете использовать методы, которые мешают кому-то следить за тем, что делает ваш код. В этих случаях комментарии могут и должны использоваться не только для объяснения причин такой оптимизации, но и для того, что делает код. Хорошее практическое правило - попросить кого-то (или нескольких других людей) ознакомиться с языком реализации и проектом взглянуть на ваш код - если они не могут понять, почему и как, то вы должны прокомментировать и почему, и как.
Однако в коде неясно, почему вы что-то сделали. Если вы используете подход, который может быть неочевиден для других, у вас должен быть комментарий, объясняющий, почему вы приняли решения, которые вы сделали. Я подозреваю, что вы можете даже не осознавать, что комментарий необходим, пока после чего-то вроде проверки кода, когда люди хотят знать, почему вы сделали X вместо Y - вы можете записать свой ответ в коде для всех, кто смотрит на него в будущем.
Однако самое важное - это изменить ваши комментарии при изменении кода. Если вы меняете алгоритм, обязательно обновите комментарии, объяснив, почему вы выбрали алгоритм X вместо Y. Устаревшие комментарии - это еще больший запах кода.
источник
Это особенно раздражает, когда я слышал, что в эти выходные я провел некоторое время, глядя на очень хорошо названный, очень чистый, некомментированный код, реализующий алгоритм исследования (тот, который на самом деле не опубликован). Я хорошо знаком с этим, парень, который сидел рядом со мной, был изобретателем, а код был написан несколько лет назад кем-то другим. Мы едва могли следовать этому.
Ваш коллега недостаточно опытен, очевидно.
источник
Комментарии должны объяснять почему, а не как.
How
комментарии типа обычно лучше обрабатываются с помощью рефакторинга. Лично я обычно избегаю комментариев в пользу рефакторинга.До:
после:
источник
Я объявляю вашего коллегу еретиком! Где мои еретические сапоги?
Навязчивое комментирование - это плохо, и головная боль в обслуживании, и комментарии не заменяют хорошо названные методы, классы, переменные и т. Д. Но иногда объяснение, почему что-то так, может быть очень ценным для бедного идиота, который должен поддерживать код через шесть месяцев - особенно когда этот бедный идиот оказывается тобой.
Некоторые реальные комментарии из кода, над которым я работаю:
источник
SomebodyScrewedAroundWithDatabaseException
...В идеале код должен быть настолько хорошо закодирован, что он должен быть автоматически объяснительным. В реальном мире мы знаем, что также очень качественный код иногда нуждается в комментировании.
Чего вам следует избегать, так это «избыточности кода комментария» (комментарии, которые ничего не добавляют к коду):
Затем, если есть хороший (и поддерживаемый / выровненный) дизайн кода и документация, комментирование еще менее полезно.
Но в некоторых случаях комментарии могут помочь в удобочитаемости кода:
Не забывайте, что вы должны поддерживать и синхронизировать также комментарии ... устаревшие или неправильные комментарии могут быть ужасной болью! И, как правило, слишком частое комментирование может быть признаком плохого программирования.
источник
} //end while
просто означает, что начало цикла while так далеко, что вы даже не можете его увидеть, и нет никаких намеков на то, что код, который вы просматриваете, находится в цикле. Тяжелый рефакторинг должен быть серьезно предпочтен комментариям о том, как структурирован код.} // end while
комментарии могут быть спасением.Категорически определяя метод или процесс как «запах кода» - это «запах фанатизма». Термин становится новым «считается вредным».
Пожалуйста, помните, что все эти вещи должны быть ориентирами.
Многие другие ответы дают хороший совет относительно того, когда комментарии являются обоснованными.
Лично я использую очень мало комментариев. Объясните цель неочевидных процессов и оставьте случайную смертельную угрозу для любого, кто может подумать о том, чтобы изменить вещи самостоятельно, что потребовало недель настройки.
Рефакторинг всего до тех пор, пока ученик не поймет, что это, вероятно, неэффективное использование вашего времени, и, вероятно, не будет работать так же хорошо, как более краткая версия.
Комментарии не влияют на время выполнения, поэтому единственная отрицательная проблема, которую следует учитывать, - это обслуживание.
источник
В некоторых случаях никакие хорошие названия, рефакторинг и т. Д. Не могут заменить комментарий. Просто посмотрите на этот реальный пример (язык Groovy):
Выглядит странно, не правда ли? Вероятно, ошибка копирования-вставки? Плачет об ошибке?
Теперь то же самое с комментариями:
источник
Основной проблемой здесь является значение термина «кодовый запах».
Многие люди (включая вас, я думаю) понимают запах кода как нечто, близкое к ошибке или, по крайней мере, что-то, что нужно исправить. Возможно, вы думаете об этом как синоним «анти-паттерна».
Это не значение термина!
Метафора запаха кода происходит из Wiki Wards , и они подчеркивают:
Так что же означает, что комментарии - это запах кода: это означает, что когда вы видите комментарий, вы должны остановиться и подумать: «Хммм, я чувствую намек на то, что что-то можно улучшить». Возможно, вы можете переименовать переменную, выполнить «извлечение метода» - рефакторинг - или, возможно, комментарий на самом деле является лучшим решением.
Вот что значит для комментариев быть запахами кода.
РЕДАКТИРОВАТЬ: я просто наткнулся на эти две статьи, что объясняет это лучше, чем я:
источник
Я думаю, что правило довольно простое: представьте совершенно незнакомого человека, который видит ваш код. Вы, вероятно, будете незнакомым со своим собственным кодом через 5 лет. Постарайтесь минимизировать умственные усилия, чтобы понять ваш код для этого незнакомца.
источник
Хорошая идея иметь правильные комментарии - начать с написания комментариев.
Это позволяет вам легко извлекать методы, чтобы даже избавиться от комментариев,
просто позвольте коду рассказать об этом ! Посмотрите, как это переписано (вырезано / вставлено) очень хорошим способом:
Для вещей, которые нельзя отделить, просто не извлекайте методы и вводите код под комментариями.
Это то, что я считаю полезным для продолжения комментирования до минимума, действительно бесполезно комментировать каждую строку ... Документируйте только одну строку, если речь идет об инициализации магического значения или там, где это имеет смысл.
Если параметры используются слишком часто, то они должны быть частными членами вашего класса.
источник
Я думаю, что ответ является обычным "Это зависит" один. Комментирование кода только для комментирования кода является запахом. Комментирование кода, потому что вы используете непонятный алгоритм, который на порядок быстрее, экономит программисту по обслуживанию (обычно мне через 6 месяцев после того, как я его написал) полдня просмотра кода, чтобы определить, что он делает.
источник
или же
источник
Комментарии к коду определенно не являются «запахом кода». Это убеждение обычно исходит из того факта, что комментарии могут устареть (устареть) и их трудно поддерживать. Однако наличие хороших комментариев, которые объясняют, почему код делает что-то определенным образом, может (и обычно) важно для обслуживания.
источник
Если код был написан особым образом, чтобы избежать проблемы, присутствующей в библиотеке (сторонней библиотеке или библиотеке, которая поставляется с компилятором), то имеет смысл прокомментировать это.
Также имеет смысл комментировать код, который необходимо изменить в будущих версиях, или при использовании новой версии библиотеки, или при переходе от PHP4 к PHP5, например.
источник
Даже самая хорошо написанная книга все еще, вероятно, имеет введение и названия глав. Комментарии в хорошо документированном коде все еще полезны для описания концепций высокого уровня и объяснения того, как организован код.
источник
Следует отметить анти-шаблон:
У меня сложилось впечатление, что иногда предварительные примеры лицензий FLOSS часто используются вместо файловой документации. GPL / BSDL создает приятный текст для заполнения, и после этого вы редко видите какой-либо другой блок комментариев.
источник
Я не согласен с мыслью, что написание комментариев для объяснения кода - это плохо. Это полностью игнорирует тот факт, что код имеет ошибки. Может быть понятно, что код делает без комментариев. Менее вероятно, будет ясно, что код должен делать. Без комментариев, как вы узнаете, если результаты неверны, или они используются неправильно?
Комментарии должны объяснять цель кода, чтобы в случае ошибки кто-то, читающий код «Комментарии +», имел шанс найти его.
Я обычно пишу встроенные комментарии, прежде чем писать код. Таким образом, становится ясно, что я пытаюсь написать код, и уменьшаются потери в алгоритме, даже не зная, что вы пытаетесь сделать.
источник
Комментарии, которые вводятся потому, что кто-то считает, что в одном методе 700 строк, - это запах.
Комментарии, которые есть, потому что вы знаете, что если вы не добавите комментарий, кто-то совершит ту же ошибку, все еще будет запахом.
Комментарии добавлены, потому что некоторые инструменты анализа кода требуют, чтобы это также было запахом.
Люди, которые никогда не будут комментировать или даже помогать другим разработчикам, тоже пахнут. Я поражен тем, как много людей не будут записывать вещи, но потом повернутся и признают, что не могут вспомнить, что они сделали 3 месяца назад. Я не люблю писать документы, но мне нравится говорить людям одно и то же снова и снова, даже реже.
источник
Я отвечу своим вопросом. Можете ли вы найти ошибку в некомментированном коде ниже?
tl; dr: следующий человек, который будет поддерживать ваш код, может быть не таким богоподобным, как вы.
источник
Вы должны сохранять баланс между кодом и комментариями ... Обычно я пытаюсь добавить некоторые комментарии, которые возобновляют блок кода. Не потому, что я не смогу понять код (ну, это тоже), а потому, что я могу быстрее читать свой собственный код и находить определенные разделы, где происходят важные вещи.
В любом случае, мой личный критерий - «когда сомневаешься, комментируй». Я предпочитаю иметь избыточную линию, чем полностью загадочную строку, которую я не смогу понять. Я всегда могу удалить комментарии к обзору кода, через некоторое время (и я обычно делаю)
Кроме того, комментарии очень полезны, добавляя «предостережения», такие как «Будьте осторожны! Если формат ввода не ASCII, этот код придется изменить!»
источник
Прочитав это, я вспомнил кое-что, что я впервые прочитал (из более длинного списка, сохраненного с помощью фотокопий) несколько десятилетий назад:
Довольно старый запах метинкс.
источник
Я думаю, что комментирование кода становится очень плохим началом жизни. Я не знаю об этих днях, но когда меня впервые учили программированию в школе, я получил задание типа «Напишите программу, которая печатает числа от одного до десяти в отдельных строках. Обязательно прокомментируйте свой код». Вы были бы отмечены, если бы не добавляли комментарии, потому что комментировать ваш код - ХОРОШАЯ вещь.
Но что можно сказать о таком тривиальном процессе? Итак, вы заканчиваете тем, что пишете классический
просто чтобы получить достойную оценку и, если у вас вообще есть ню, мгновенно сформировать очень низкое мнение о комментариях к коду.
Комментирование кода - это НЕ ХОРОШО. Это НЕКОТОРЫЕ НЕОБХОДИМЫЕ вещи, и Томас Оуэнс в верхнем ответе дает превосходное объяснение ситуаций, в которых это необходимо. Тем не менее, эти ситуации редко возникают в домашних заданиях.
Во многих отношениях добавление комментария следует рассматривать в качестве крайней меры, когда то, что необходимо сказать, не может быть четко сказано в активных частях языка программирования. Хотя именование объектов может устареть, различные механизмы отсутствия обратной связи с человеком и компьютером позволяют легко забыть поддерживать комментарии, и, следовательно, комментарии устаревают гораздо быстрее, чем активный код. По этой причине, когда выбор возможен, изменение кода, чтобы сделать его более понятным, всегда должно быть предпочтительнее, чем комментировать неясный код комментариями.
источник
Конечно, комментарии - это запах кода ...
каждый программист знает, что все мы в конечном итоге сходим с ума из-за объема работы, отладки или просто безумия, с которым мы сталкиваемся.
"Сделай это!" Ваш менеджер проекта говорит.
Вы отвечаете: «Это невозможно сделать».
Они говорят: «Тогда мы найдем кого-то еще, чтобы сделать это».
Вы говорите: «Хорошо, хорошо, может быть, это можно сделать».
А затем потратьте следующие X дней ... недель ... месяцев ... пытаясь понять это. На протяжении всего процесса вы будете пытаться и терпеть неудачу, и пытаться и терпеть неудачу. Мы все делаем это. Правильный ответ: есть два типа программистов: те, которые комментируют, и те, которые этого не делают.
1) Те, кто это делает, либо делают свою собственную работу проще, документируя для дальнейшего использования, комментируя неудачные подпрограммы, которые не работали (запах не удаляет их после нахождения той, которая работает.), Или разбивают код с комментарием форматирование, чтобы, надеюсь, сделать его немного легче для чтения или понимания. Серьезно, я не могу их винить. Но, в конце концов, они ломаются, и тогда у вас есть это:
// dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!
2) Те, кто не притворяется супергероем, или живут в пещере . Они просто безрассудно пренебрегают другими людьми и могут меньше заботиться о коде или о том, какое значение он может иметь в будущем.
Не поймите меня неправильно ... самодокументированные переменные и функции могут полностью этого избежать ... и поверьте мне, вы никогда не сможете сделать достаточно очистки кода. Но простая истина в том, что пока вы храните резервные копии, вы ВСЕГДА можете удалять комментарии.
источник
Я бы утверждать , что не использует некоторые комментарии в коде это код запах. Хотя я согласен с тем, что код должен как можно больше самодокументироваться, вы попадаете в определенную точку, где вы увидите код, который не имеет смысла независимо от того, насколько хорошо код написан. Я видел некоторый код в бизнес-приложениях, где комментарии в значительной степени обязательны, потому что:
Кроме того, руководства по фирменному стилю могут сказать вам, что вы должны сделать что-то определенным образом - если они говорят, что у вас могут быть комментарии, описывающие, что делают блоки кода в функции, то включайте комментарии.
источник
Между комментариями и кодом есть большая принципиальная разница: комментарии - это способ, которым люди могут делиться идеями с другими людьми, тогда как код предназначен в первую очередь для компьютера. В «коде» есть много аспектов, которые также предназначены только для людей, например, присвоение имен и отступов. Но комментарии написаны исключительно для людей, людьми.
Поэтому писать комментарии так же сложно, как и любое человеческое общение! Автор должен иметь четкое представление о том, кто является аудиторией, и какой текст им понадобится. Как узнать, кто будет читать ваши комментарии через десять, двадцать лет? Что если человек из совершенно другой культуры? И т.д. Я надеюсь, что все это понимают.
Даже внутри небольшой гомогенной культуры, в которой я живу, просто так сложно передавать идеи другим людям. Человеческое общение обычно терпит неудачу, кроме как случайно.
источник
Я должен согласиться с вашим коллегой. Я всегда говорю , что если я комментирую свой код, это означает , что я боюсь , что я не смогу выяснить свой собственный код в будущем. Это плохой знак.
Единственная другая причина, по которой я добавляю комментарии в код, - это вызывать что-то, что, кажется, не имеет смысла.
Эти комментарии обычно принимают форму чего-то вроде:
или же
источник
Комментарии к коду, дающие, где это применимо, единицы аргументов и возвратов функций, поля структуры, даже локальные переменные, могут быть очень полезными. Помните орбитальный аппарат Марса!
источник
Вот мое эмпирическое правило:
источник
Расскажите своему коллеге о технике грамотного программирования .
источник
Нет, комментарии не являются запахом кода, они просто инструмент, которым можно злоупотреблять.
Примеры хороших комментариев:
// Я думаю, что это в см. Требуется дальнейшее расследование!
// Это умный способ сделать X
// Здесь список гарантированно не пуст
источник
Assert(list.IsEmpty)
?Assert(!list.isEmpty())
- это не просто контракт, как в третьем комментарии, а просто поведение (то есть «выбросить IllegalArgumentException, если аргумент пуст»), которое должно быть проверено модулем, как любая другая программная логика. Обратите внимание на небольшую разницу с комментарием, в котором указывается, когда метод может быть использован, но не указывается поведение, если предварительное условие не выполняется. Даже лучше, чем комментарий, было бы обеспечить выполнение контрактов во время компиляции. Но это выходит за рамки моего ответа;)Assert
s, поскольку они описывают вещи, которые не должны происходить, даже если общедоступный API получает недопустимые аргументы.