Больше комментариев лучше в средах с высоким оборотом?

11

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

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

joshin4colours
источник
8
Как вы думаете, что произойдет, когда вы перейдете к другому проекту или другой работе, и кто-то другой должен будет поддерживать ваш код? Является ли ваш код действительно так чисто и ясно , что кто - то будет легко понять , что вы делаете и почему?
Калеб
2
Много хорошего хватает в существующих ответах. Но просто хотел сказать, что если сейчас / несколько юнит-тестов, потратьте время на создание тестов, а не комментариев, для среды с высокой текучестью. Если для комментариев осталось время, добавьте комментарии «почему» и в код, и в тесты.
Джеймс Янгман
@Caleb Даже если бы он не был чистым и понятным, вы действительно думаете, что поверхностные комментарии повсюду помогут? Почему бы просто не написать какую-нибудь документацию в другом месте с описаниями?
joshin4colours

Ответы:

22

Комментарии не загромождают код.

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

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

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

Яннис
источник
9
+1, Excessive commenting can only hurt when comments are concentrated on the how and not the whyза исключением того, что я сделал бы еще один шаг вперед и сказал бы, что ЛЮБЫЕ комментарии плохи, когда они объясняют, как, а не почему .
maple_shaft
Comments don't clutter the code.Ну, это зависит, особенно если вы используете #.
Динамичный
11

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

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

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

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

прецизионный самописец
источник
6
Тщательный анализ кода должен ставить под сомнение чрезмерные комментарии разработчика, но вы абсолютно правы, что ее команда получит гораздо больше пользы от регулярных проверок кода, чем от плодотворных комментариев.
maple_shaft
4
«Качественный, читаемый код никогда не должен нуждаться в дополнительных комментариях, чтобы объяснить, что он делает». - Что не относится к 90% написанного кода.
Оливер Вейлер
1
@OliverWeiler: Таким образом, 90% написанного кода можно сделать с хорошим обзором кода. У меня было 5 старших разработчиков в команде, где весь код был проверен по крайней мере еще одним старшим, и в результате они создали очень читаемый код с минимумом комментариев.
фунтовые
1
@pdr Для многих команд и большинства приложений предположение о наилучшем сценарии качества и читаемости кода является катастрофой. Каждый думает, что его код совершенно понятен. Истина в этом вопросе часто очень отличается.
Дэйв
1
@ Дэйв: Я не предлагаю, чтобы вы что-то предполагали. Вы проверяете качество кода, передавая его другому разработчику и говоря: «Вы можете прочитать и понять это?» Это гораздо более надежное руководство, чем «Я надеюсь, что эти комментарии делают его читабельным» и имеет более быстрый цикл обратной связи (т. Е. Вы можете переписать код или добавить комментарий, пока он еще свеж в вашем уме).
фунтовые
6

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

Цель состоит в том, чтобы сделать кодовую базу легкой для понимания и изменения. Вы можете сделать это, хотя и свободно используете комментарии (хотя вы можете столкнуться с проблемой из комментариев к данным), или вы можете написать самодокументируемый код (насколько это возможно), и использовать комментарии только для объяснения нетривиального «почему» " вопросы. Любой подход может сработать, но учтите, что для изменения кода вам нужно понимать сам код, а не только комментарии. Поэтому, хотя комментарии могут помочь вам понять код, в конце концов вам, вероятно, все равно придется понимать сам код. С учетом сказанного я предпочитаю подход самодокументируемого кода. Кажется, это более прямой способ создания чистой кодовой базы.

Oleksi
источник
5

"Являются ли больше комментариев лучше в средах с высоким оборотом?"

Я думаю, что они могут быть еще хуже

  • Разные авторы будут использовать разные стили и уровни детализации и меньше будут обновлять комментарии других людей.

  • Мнение «Что нужно комментировать» меняется от человека к человеку.

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

  • Поддержание их формата и последовательности становится работой само по себе.

  • Новые пользователи должны изучить стандарт «формат», прежде чем они смогут быстро вносить изменения.

Майкл Даррант
источник
3
Перечисленные вами проблемы также являются проблемами самого кода в среде с высокой текучестью, а не только комментариями. Это ... интересно;) Больше проблема людей, чем проблема кода / комментариев.
Яннис
+1 Привет, Яннис, да, это очень хороший момент. Согласен. Я также думаю, что, поскольку сам код немного более структурирован - имеет фиксированные имена для определенных вещей, самый простой пример - функция "to_string" не имеет двусмысленности, поэтому ее следует называть так, поскольку комментарии имеют абсолютно нулевую структуру или согласованы с терминами. , что делает комментарии хлопотными. С другой стороны, в коде может появиться гораздо больше «спагетти», чем комментариев. Интересный.
Майкл Даррант
4

Пункт 1: ясность важна в условиях высокой текучести

Пункт 2: многословие не ясность

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

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

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

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

  • Лучшие имена переменных и функций
  • Лучшее расположение кода и пробелы
  • Удалите все "уловки", которые вы считаете хорошей идеей
  • Группируйте код в соответствии с концептуальной функцией (например, извлекайте код для конкретной цели в функцию с соответствующим именем, даже если вы вызываете ее только один раз)
  • Используйте более простой алгоритм (если позволяют условия)
  • Используйте общеизвестные библиотеки для общей функциональности
tylerl
источник
1

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

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

MathAttack
источник
1

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

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

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

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

Дейв
источник