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

100

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

Fishtoaster
источник
44
Я собираюсь поднять любой ответ, который говорит «нет».
Николь
2
@Renesis Это запах божественности.
ixtmixilix
107
Ваш коллега сделал широкое обобщение, что автоматически означает, что он не прав. :)
Алекс Фейнман
5
@ Монгус, я не согласен. Комментарии в вашем примере плохи не потому, что они являются комментариями, а потому, что они СЛИШКОМ близки к коду, который затем изменяется. Они должны сказать ПОЧЕМУ, а не ЧТО .
5
@ Алекс, разве это не общее обобщение, которое поэтому неверно (в результате чего он все равно не ошибается)?

Ответы:

167

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

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

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

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

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

Томас Оуэнс
источник
8
Я согласен с этим ответом в отношении комментариев, но я также видел его в качестве оправдания отсутствия документации, что неправильно. Чтение кода иногда вызывает боль в заднице. Вам не нужно смотреть на код метода, чтобы выяснить, что делает этот метод. Вы должны быть в состоянии выяснить это по названию и получить более подробную информацию из документов. При чтении кода вам часто приходится переключаться из класса в класс и из файла в файл. Это особенно проблема в динамических языках, где написание IDE, которая может справиться со всем этим, нетривиально.
Давидтбернал
1
В любом случае, иногда вы также должны комментировать, КАК это сложно (особенно, если это оптимизировано или любые другие нетривиальные операции). Если мне придется потратить более 5 минут на чтение одного блока кода, чтобы понять, что он делает, это может быть довольно неприятно ...
Хелбен
3
«Только если комментарий описывает, что делает код». Или если комментарий описывает то, что код делал; код изменился, но комментарий не изменился.
Брюс Олдерман
1
Как вы проверяете, что ваш комментарий правильный? Почему бы не написать свой комментарий в качестве теста? Любой будущий сопровождающий может использовать тест в качестве проверяемой документации для кода. Если комментарий как-то связан с выполнением кода, то это что-то / должно / быть подтверждено. Если комментарий не имеет ничего общего с выполнением кода, то что он делает в коде, куда будут смотреть только программисты?
Flamingpenguin
2
@ back2dos, если вас часто рвет, когда вы читаете код других людей, я рад, что мы не
110

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

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

Пол Натан
источник
16
Мне любопытно взглянуть на «хорошо названный, очень чистый, некомментированный код», за которым трудно следить. Любой код, который я бы классифицировал как таковой, был очень легко понятен. Я, конечно, не пошел бы так далеко, как «Ваш коллега, очевидно, недостаточно опытен».
Лиги
8
@Liggy: я бы. Это алгоритм исследования, а не бизнес-приложение.
Пол Натан
9
Когда-то у меня был фрагмент кода, в котором вам нужно было заполнить поля в объекте столбца базы данных (третье лицо) в «неправильном» порядке (определяемом «логикой» процесса и нашими стандартами кодирования) - делайте это в том порядке, в котором мы обычно использовал бы, и это потерпело бы крах. Никакое количество чтения кода не может сказать вам об этом, так что положительно, безусловно, должен был быть комментарий - и это не был запах, по крайней мере, не в коде, который мы контролировали (что является нижней строкой). Полное и полное отсутствие комментариев - такой же запах, как и плохие комментарии.
Murph
29
Математика, математика, математика. Не весь код реализует тривиальный клей IoC и «цена * количество». Сложная математика не может быть волшебным образом объяснена.
bmargulies
4
@Liggy, код, реализующий сложные структуры данных, может быть совершенно непонятным без обширной документации.
75

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

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)
Сэм Шафран
источник
26
Я согласен с тем, почему, а не как часть, и ваш рефакторинг работает в этом примере, но с более сложным кодом, никакое количество переименования / рефакторинга переменных / функций не будет иметь этого смысла, и комментарии все равно будут там нужны.
GSto
3
Хороший пример, но почему система работает с центами, а не с долларами? Этот вопрос становится актуальным в финансовых системах, где вы можете увидеть, что в игру вступает дробная валюта.
rjzii
3
@ Запустите имя функции, которая должна сказать, что она делает.
Альб
3
@GSto, я не мог не согласиться больше. Если код сложный, его следует разбить на более мелкие методы / функции с соответствующими именами, которые описывают действие.
CaffGeek
1
Вы предполагаете, что имеете полный контроль над кодовой базой.
LennyProgrammers
32

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

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

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


    // 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.

BlairHippo
источник
7
+1 за приятные комментарии. Никакой объем кода не может сказать: «Если это произойдет, кто-то пошутил с определениями базы данных».
DistantEcho
9
@Niphra, ну, мы могли бы бросить SomebodyScrewedAroundWithDatabaseException...
@ Thorbjørn +1, если код знает, что случилось, черт возьми, сообщите об этом. Клиенты службы поддержки могут, вероятно, перезагрузить свою БД и избежать обращения в сервис.
Тим Уиллискрофт
@ Тим, как клиенты могут увидеть это, может быть целесообразным более нейтральное наименование.
3
Конечно, помните: никогда не используйте глупые имена. Клиент всегда их увидит.
Тим Уиллискрофт
29

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

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

i++; // Increment i by 1

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

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

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

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

Лоренцо
источник
2
Хорошее соглашение об именах и хорошо структурированный код помогут вам уменьшить потребность в комментариях. Не забывайте, что каждая добавленная вами строка комментариев - это новая строка для поддержки !!
Габриэль Монгеон
81
Я ненавижу, когда люди используют второй пример в вашем вопросе. } //end whileпросто означает, что начало цикла while так далеко, что вы даже не можете его увидеть, и нет никаких намеков на то, что код, который вы просматриваете, находится в цикле. Тяжелый рефакторинг должен быть серьезно предпочтен комментариям о том, как структурирован код.
Карсон Майерс
4
@Carson: хотя держать блоки короткими - это хорошо известное правило, это не значит, что мы всегда можем его применять.
Wizard79
4
@Carson: В одном из проектов, над которым я работаю, недостаточно обзор кода, что привело к созданию JSP с цикломатической сложностью «OMFG JUST KILL YOURSELF». Рефакторинг кровавых вещей представляет собой дни работы, которые нужно потратить в другом месте. Эти } // end whileкомментарии могут быть спасением.
BlairHippo
11
@BlairHippo: «Запах кода [A] - это любой признак в исходном коде программы, который, возможно, указывает на более глубокую проблему». Конечно, комментарий спасает жизнь, но цикл OMGWTF - это вышеупомянутая «более глубокая проблема», и необходимость спасателя - явный индикатор;)
back2dos
26

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

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

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

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

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

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

Билл
источник
8
Я думал, что «анти-паттерн» был новым, «считающимся вредным». Запах кода - это просто то, что требует более тщательного анализа для возможной очистки.
Джеффри Хантин
1
Я не согласен с тем, что анти-шаблон также подходит. Они оба привыкли использовать анти-шаблон вместо запаха, когда дизайн достаточно сложный, что, очевидно, является осознанным выбором. В любом случае я не согласен с концепцией, что существует абсолютный источник правильности этих вещей.
Билл
4
+1 за «Рефакторинг всего до тех пор, пока воспитатель не поймет, что это, вероятно, неэффективное использование вашего времени и, вероятно, не будет работать так же хорошо, как более краткая версия».
Эрлз
23

В некоторых случаях никакие хорошие названия, рефакторинг и т. Д. Не могут заменить комментарий. Просто посмотрите на этот реальный пример (язык 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
user281377
источник
function prime_extjs_uploadform () {response.contentType = 'text / html'; render '{"success": true}'; } prime_extjs_uploadform ();
DrPizza
23

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

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

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

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

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

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

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

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

Расмус Фабер
источник
2
Я ошеломлен, что потребовалось 2 месяца для этого ответа, чтобы придумать. Это показывает, насколько широко распространено недопонимание этого термина.
Пол Бучер
Общее утверждение по-прежнему неверно. Вы не говорите: «Я вижу прокомментированный код. Это плохой знак».
Стюарт П. Бентли
1
@Stuart: вы смотрите на два куска кода, оба с соответствующими уровнями комментариев. (Эта проблема не о соответствующем количестве комментариев, а о том, как вы оцениваете код по количеству комментариев.) У одного нет комментариев, у другого - тонны. На что вы смотрите более внимательно? - Комментарии являются признаком того, что код сложный и тонкий, и, следовательно, с большей вероятностью возникнут проблемы
Дэвид Шварц
Это правильный ответ.
Виджет
21

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

LennyProgrammers
источник
8
+1 Для любого разработчика , который не работал на одном проекте достаточно долго , чтобы испытать это, поверьте мне , это будет происходить. Каждый раз, когда я усваиваю это нелегко и мне приходится переучивать свой собственный код, я не позволяю себе дважды совершать одну и ту же ошибку и комментирую ее, прежде чем перейти к чему-то другому.
Николь
Нет, вы должны представить себе психопата, который знает, где вы живете: будут ли они рады поддерживать ваш код?
Ричард
4
Я регулярно становлюсь психопатом, когда вижу нечитаемый код.
LennyProgrammers
3
5 лет? Больше похоже на 5 минут. ;)
Алекс Фейнман
11

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

// 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 ...

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

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

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

оборота Том Вейсман
источник
1
Это то чем я занимаюсь. Если вы считаете, что вам нужны комментарии, я от всей души рекомендую попробовать это в качестве замены.
2010 г.
10

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

Brandon
источник
10
// 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.
Zzz
источник
Ах, сердечные просьбы будущему я.
Энтони Пеграм
8

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

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

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

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

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

Скотт Дорман
источник
1
Комментарии могут устареть, но это верно для всего, что не проверено компилятором или модульным тестом, например значения имен классов, функций и переменных.
LennyProgrammers
@ Lenny222: Да, комментарии могут устареть ... что обычно свидетельствует о ленивых программистах. Если комментарий описывает, почему было принято решение, почему код использует определенный алгоритм для вычисления, или описывает, как код функционирует, то нет никаких причин для того, чтобы комментарий стал устаревшим, кроме того, что кто-то изменил реализацию и не обновил комментарий соответствующим образом. - что эквивалентно тому, чтобы быть ленивым.
Скотт Дорман
2
Я согласен. Я хочу сказать, что есть риск, что это станет устаревшим, да. Но когда у меня есть функция doBar (), и через 3 года она не «делает бар», а «делает бар и фу, кроме среды», тогда значение функций может устареть. И имена переменных. Но я надеюсь, что никто не принимает это по причине, чтобы не давать функциям и переменным значащие имена.
LennyProgrammers
6

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

оборота киамлалуно
источник
6

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

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

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

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

марио
источник
4

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

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

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

Дэнни Таппени
источник
1
Модульные тесты очень помогают определить, если результаты неверны. Если вы читаете некоторый код и думаете, что он делает X, тогда как на самом деле он делает Y, тогда возможно, что код написан недостаточно читабельным способом. Я не уверен, что вы имеете в виду, что результаты используются неправильно. Комментарий не защитит вас от того, кто использует ваш код странным образом.
Адам Лир
«Если вы читаете некоторый код и думаете, что он делает X, тогда как на самом деле это делает Y» Я не это сказал. Я говорю о понимании того, что делает код , но не о том, что он должен делать. Допустим, вы подозреваете ошибку «один за другим». Откуда вы знаете, что ошибка «один за другим» отсутствует в коде потребления или в этом коде? Комментарии объясняют цель кода, который очень помогает при поиске ошибок.
Дэнни Таппени
С другой стороны, комментарии могут только сказать вам, что должен был делать код на момент написания комментариев. Сам код может сообщать вам, что он должен делать сейчас. Комментарии не компилируются. Вы не можете проверить комментарии. Они могут или не могут быть правильными.
Энтони Пеграм
3

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

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

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

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

MIA
источник
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
Муравей
источник
Но, кстати, в наши дни вы не используете язык высокого уровня?
Ян
2
@Ian: Программа представляет собой загрузчик IBM-PC. Вы не можете записать его ни в чем, кроме сборки, потому что вам нужен полный контроль над тем, где именно находится программа в ОЗУ, где появляется последнее короткое замыкание и некоторые аппаратные прерывания. Серьезно, получите себе копию NASM. Соберите его, запишите его в загрузочный сектор дискеты или USB-накопителя и загрузите его. Хотя вы, вероятно, обнаружите, что это не работает должным образом из-за ошибки. Теперь найдите ошибку ... Несмотря на это, я уверен, что через 20 лет люди будут спрашивать то же самое о незакомментированной Java.
Муравей
Конечно, код может быть написан на C или C ++, а двоичный файл собран из объектного кода C и некоторого внешнего инструмента.
Кевин Клайн
К сожалению нет. Взгляните на эту страницу на CodeProject: codeproject.com/KB/tips/boot-loader.aspx - «языки высокого уровня не имеют необходимых инструкций». Не только это, но у вас есть только 512 байт для игры в загрузчике. Иногда вам просто нужно перейти непосредственно к оборудованию.
Муравей
1
Когда я пишу код сборки, я делаю то, что делают все остальные - комментирует каждую строку с тем, что делает. В рассматриваемой строке был бы комментарий «проверим ли буква на 0», так как в коде используются строки в конце в стиле C. С этим комментарием легко увидеть, что код выполняет cmp с 1, что означает, что он либо застревает в бесконечном цикле, либо печатает мусор, пока не достигнет случайного 1 в ОЗУ. Я мог бы также добавить комментарий о том факте, что строки заканчивались 0, что не видно из кода. Существует ли такая вещь, как автоматизированное модульное тестирование для кодирования сборки?
Муравей
2

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

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

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

Khelben
источник
Не могли бы вы объяснить, что вы подразумеваете под «комментариями, которые возобновляют блок кода»?
Марк C
2

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

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

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

Murph
источник
2

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

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

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

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

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

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

Alohci
источник
+1 за указание, что плохие привычки комментирования начинаются с ранних классов программирования. -1 за вывод о том, что комментарии являются лишь последним выбором.
AShelly
1

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

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

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

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

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

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

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

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

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

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

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

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

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

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

rjzii
источник
1

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

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

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

user15127
источник
0

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

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

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

//xxx what the heck is this doing??

или же

// removed in version 2.0, but back for 2.1, now I'm taking out again
кругозор
источник
1
Или, в качестве альтернативы, комментарий может отражать тот факт, что код обращается к сложному алгоритму, в котором код становится по своей сути неочевидным, или потому что код делает что-то странное из-за факторов, находящихся вне вашего контроля (например, взаимодействие с внешней службой).
Murph
Очень верно. Есть причины, по которым хороший код может быть неочевидным. Хотя большую часть времени код ставит в тупик, потому что он написан запутанным образом.
Кен,
Похоже, вы не написали код для встраиваемых процессоров, где у вас есть только 32K для игры, и это делает вашу ставку неясной. Комментарии спасают.
quick_now
0

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

dmuir
источник
Гораздо лучше встраивать модули в имена переменных, чтобы плохому программисту не приходилось их запоминать. Вместо «двойной длины // в метрах» произнесите «double length_m». Лучше всего использовать более мощный язык, поэтому вы можете просто сказать Длина l; Сила f; Крутящий момент t = l * f; печати (t.in (Torque.newtonMeter));
Кевин Клайн
0

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

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

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

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

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

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

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

Андрес Ф.
источник
Третий - плохой комментарий IMO. Почему нет Assert(list.IsEmpty)?
CodesInChaos
@CodeInChaos IMO Assert(!list.isEmpty())- это не просто контракт, как в третьем комментарии, а просто поведение (то есть «выбросить IllegalArgumentException, если аргумент пуст»), которое должно быть проверено модулем, как любая другая программная логика. Обратите внимание на небольшую разницу с комментарием, в котором указывается, когда метод может быть использован, но не указывается поведение, если предварительное условие не выполняется. Даже лучше, чем комментарий, было бы обеспечить выполнение контрактов во время компиляции. Но это выходит за рамки моего ответа;)
Андрес Ф.
Вы не должны иметь возможность использовать Asserts, поскольку они описывают вещи, которые не должны происходить, даже если общедоступный API получает недопустимые аргументы.
CodesInChaos
@CodeInChaos Я отказываюсь от своего мнения. Вот что Sunacle должен сказать об утверждениях . Кажется, ты был прав. Ну, вы чему-то учитесь каждый день!
Андрес Ф.