«Комментарии - это запах кода» [закрыто]

Мой коллега считает, что любое использование комментариев в коде (т. Е. Не метод стиля javadoc или комментарии класса) является запахом кода . Как вы думаете?

Только если комментарий описывает, что делает код.

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

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

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

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

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

Ваш коллега недостаточно опытен, очевидно.

Комментарии должны объяснять почему, а не как.

Howкомментарии типа обычно лучше обрабатываются с помощью рефакторинга. Лично я обычно избегаю комментариев в пользу рефакторинга.

До:

# convert to cents
a = x * 100

# avg cents per customer 
avg = a / n

# add to list
avgs < avg
t += 1

после:

total_cents = total * 100
average_per_customer = total_cents / customer_count

track_average(average_per_customer)

Я объявляю вашего коллегу еретиком! Где мои еретические сапоги?

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

Некоторые реальные комментарии из кода, над которым я работаю:

    // If this happens, somebody's been screwing around with the database definitions and
    // has removed the restriction that a given alarm may have only one entry in the 
    // notifications table.  Bad maintenance programmer!  Bad!  No biscuit!



    // If an alert is active on our side but inactive on theirs, that might mean
    // they closed the alert.  (Or that we just haven't told them about it yet.)  The
    // logic comes later; for now, we'll just compile it in a list.



    // If we know for a fact that an alarm isn't getting through, we're going to whine pretty
    // aggressively about it until it gets fixed.

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

Чего вам следует избегать, так это «избыточности кода комментария» (комментарии, которые ничего не добавляют к коду):

i++; // Increment i by 1

Затем, если есть хороший (и поддерживаемый / выровненный) дизайн кода и документация, комментирование еще менее полезно.

Но в некоторых случаях комментарии могут помочь в удобочитаемости кода:

while( foo )
{
     if( dummy )
     {
     }
     else // !dummy
     {
     }
} // end while( foo )

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

Категорически определяя метод или процесс как «запах кода» - это «запах фанатизма». Термин становится новым «считается вредным».

Пожалуйста, помните, что все эти вещи должны быть ориентирами.

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

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

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

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

В некоторых случаях никакие хорошие названия, рефакторинг и т. Д. Не могут заменить комментарий. Просто посмотрите на этот реальный пример (язык Groovy):

  response.contentType="text/html"
  render '{"success":true}'

Выглядит странно, не правда ли? Вероятно, ошибка копирования-вставки? Плачет об ошибке?

Теперь то же самое с комментариями:

  // DO NOT TOUCH THE FOLLOWING TWO LINES; the ExtJS UploadForm requires it exactly like that!!!
  response.contentType="text/html"  // must be text/html so the browser renders the response within the invisible iframe, where ExtJS can access it
  render '{"success":true}'         // ExtJS expects that, otherwise it will call the failure handler instead of the succss handler

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

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

Это не значение термина!

Метафора запаха кода происходит из Wiki Wards , и они подчеркивают:

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

Так что же означает, что комментарии - это запах кода: это означает, что когда вы видите комментарий, вы должны остановиться и подумать: «Хммм, я чувствую намек на то, что что-то можно улучшить». Возможно, вы можете переименовать переменную, выполнить «извлечение метода» - рефакторинг - или, возможно, комментарий на самом деле является лучшим решением.

Вот что значит для комментариев быть запахами кода.

РЕДАКТИРОВАТЬ: я просто наткнулся на эти две статьи, что объясняет это лучше, чем я:

• Извинения в коде
• Нужны комментарии

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

Хорошая идея иметь правильные комментарии - начать с написания комментариев.

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myFunction(parameters)
{
    // It will do some things to get started.

    // It will do more with the stuff.

    // It will end doing things with the stuff.
}

Это позволяет вам легко извлекать методы, чтобы даже избавиться от комментариев,
просто позвольте коду рассказать об этом ! Посмотрите, как это переписано (вырезано / вставлено) очень хорошим способом:

// This function will do something with the parameters, 
// the parameters should be good according to some rules.
myfunction(parameters)
{
  var someThing = initializedWithSomething;

  doSomethingWith(someThing);

  doMoreWith(someThing);

  endDoingThingsWith(someThing);

  return someThing;
}

// This function will do some things to get started,
// the parameters should be good according to some rules.
doSomethingWith(parameters)
{
  parameters.manipulateInSomeWay();
  ... etc ...
}

... etc ...

Для вещей, которые нельзя отделить, просто не извлекайте методы и вводите код под комментариями.

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

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

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

// Dear me in the future. Please, resolve this problem.

или же

// You think this code was written by somebody else. 
// No, it wasn't. You ([some name]) did it.

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

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

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

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

Самс учат себя Visual C # 2010 за 24 часа , с. 348-349.

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

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

Следует отметить анти-шаблон:

У меня сложилось впечатление, что иногда предварительные примеры лицензий FLOSS часто используются вместо файловой документации. GPL / BSDL создает приятный текст для заполнения, и после этого вы редко видите какой-либо другой блок комментариев.

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

Комментарии должны объяснять цель кода, чтобы в случае ошибки кто-то, читающий код «Комментарии +», имел шанс найти его.

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

Комментарии, которые вводятся потому, что кто-то считает, что в одном методе 700 строк, - это запах.

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

Комментарии добавлены, потому что некоторые инструменты анализа кода требуют, чтобы это также было запахом.

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

Я отвечу своим вопросом. Можете ли вы найти ошибку в некомментированном коде ниже?

tl; dr: следующий человек, который будет поддерживать ваш код, может быть не таким богоподобным, как вы.

 [org 0x7c00]

 main:
  mov ah, 0x0e
  mov bx, string
  call strreverse
  call print

 stop:
  jmp $

 strreverse:
  pusha
  mov dx, bx
  mov cx, 0

 strreverse_push:
  mov al, [bx]
  cmp al, 0
  je strreverse_pop
  push ax
  add bx, 1
  add cx, 1
  jmp strreverse_push

 strreverse_pop:
  mov bx, dx

 strreverse_pop_loop:
  cmp cx, 0
  je strreverse_end
  pop ax
  mov [bx], al
  sub cx, 1
  add bx, 1
  jmp strreverse_pop_loop

 strreverse_end:
  popa
  ret

 print:
  pusha

 print_loop:
  mov al, [bx]
  cmp al, 1
  je print_end
  int 0x10
  add bx, 1
  jmp print_loop

 print_end:
  popa
  ret
 string:
  db 'Boot up', 0

 times 510 -( $ - $$ ) db 0
 dw 0xaa55

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

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

Кроме того, комментарии очень полезны, добавляя «предостережения», такие как «Будьте осторожны! Если формат ввода не ASCII, этот код придется изменить!»

Прочитав это, я вспомнил кое-что, что я впервые прочитал (из более длинного списка, сохраненного с помощью фотокопий) несколько десятилетий назад:

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

Довольно старый запах метинкс.

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

Но что можно сказать о таком тривиальном процессе? Итак, вы заканчиваете тем, что пишете классический

i++; // add one to the "i" counter.

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

Комментирование кода - это НЕ ХОРОШО. Это НЕКОТОРЫЕ НЕОБХОДИМЫЕ вещи, и Томас Оуэнс в верхнем ответе дает превосходное объяснение ситуаций, в которых это необходимо. Тем не менее, эти ситуации редко возникают в домашних заданиях.

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

Конечно, комментарии - это запах кода ...

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

"Сделай это!" Ваш менеджер проекта говорит.

Вы отвечаете: «Это невозможно сделать».

Они говорят: «Тогда мы найдем кого-то еще, чтобы сделать это».

Вы говорите: «Хорошо, хорошо, может быть, это можно сделать».

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

1) Те, кто это делает, либо делают свою собственную работу проще, документируя для дальнейшего использования, комментируя неудачные подпрограммы, которые не работали (запах не удаляет их после нахождения той, которая работает.), Или разбивают код с комментарием форматирование, чтобы, надеюсь, сделать его немного легче для чтения или понимания. Серьезно, я не могу их винить. Но, в конце концов, они ломаются, и тогда у вас есть это: // dammit this code sucks! swear! curse! i hate it! i am going to write something here to vent my anger!!!!

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

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

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

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

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

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

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

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

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

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

Эти комментарии обычно принимают форму чего-то вроде:

//xxx what the heck is this doing??

или же

// removed in version 2.0, but back for 2.1, now I'm taking out again

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

Вот мое эмпирическое правило:

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

Расскажите своему коллеге о технике грамотного программирования .

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

Примеры хороших комментариев:

// Я думаю, что это в см. Требуется дальнейшее расследование!

// Это умный способ сделать X

// Здесь список гарантированно не пуст