Насколько комментирование лучше для кодирования? [Дубликат]

    

У этого вопроса уже есть ответ:

    

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

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

  1. Прокомментируйте адский код, например.

    unsigned int subtractor (int subtractee, int subtractor)
    {
      /*                      
         - This function is a subractor and is used to subtract one integer
           from another.
         - In other words the case here is subtractee - subtractor.  
         - Please ensure that the subractee is larger then the subtractor
           because this function will have undefined behaviour for negative
           answers.
       */
       (The code here...)    
    } 
    
  2. Код, который сам объясняет, позволяет ему (не нужно комментировать), как в этом примере. Просто используйте хорошие значащие имена.

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

Я задаю вопрос, что старший коллега по работе сказал мне делать то же, что и в (1), но теперь я читаю Робертом К. Мартином Clean Code , и на самом деле он просто утверждает, что ( 1) является плохой практикой.

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

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

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

6 голосов | спросил ITguy 28 PMpThu, 28 Apr 2016 17:33:50 +030033Thursday 2016, 17:33:50

6 ответов


23

Я всегда говорю моим разработчикам комментировать «Почему?». а не «что?» или «Как?».

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

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

Комментарий, говорящий о том, что делает код, мало мне подходит в этот момент, но комментарий, говорящий почему , код очень полезен.

Для сопровождающих (на самом деле, для кого мы помещаем комментарии) комментарии « почему » действительно полезны.

UPDATE:
Некоторые также говорят, чтобы комментировать «Что /Как» на ваш хитрый код. (Вещи, которые трудно понять.) Я согласен с этим, пока вы не можете сделать код «нецелым» и все еще выполнять требования.

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

ОБНОВЛЕНИЕ II:
«Какие» комментарии могут легко атрофироваться, поскольку сопровождающие меняют код, а не комментарии. Вот почему обильное количество комментариев может быть плохой.

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

ответил Vaccano 28 PMpThu, 28 Apr 2016 21:30:06 +030030Thursday 2016, 21:30:06
11

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

Я не думаю, что полезно писать длинные комментарии о том, как работает код или объяснять тривиальный код (например, «getName: получает имя».) Одна вещь, которую я узнал на протяжении многих лет, заключается в том, что вы не можете доверять этим типам комментарии, вы должны прочитать код и следовать ему. В лучшем случае это говорит вам, что автор думал, что код будет делать, и в худшем случае он полностью устарел и ошибается. Когда вы работаете в команде, вы часто увидите комментарии, которые были написаны для первой версии кода и никогда не обновлялись. Я даже не потрудился посмотреть на эти вещи. Это касается и проектных документов. Если вы чувствуете, что код трудно понять, вы должны его реорганизовать. Большая вещь - использование описательных и значимых имен. Это также можно зайти слишком далеко. Я знаю парня, который называет вещи с почти полными предложениями, и это слишком много шума и делает код трудным для чтения.

P.S. Я вспомнил несколько других типов комментариев, которые полезны. Когда у вас есть пустой блок кода (скажем, вы хотите скрыть конструктор по умолчанию в Java), вы должны добавить комментарий, который показывает, что он должен быть пустым. Некоторые разработчики и инструменты качества кода очень волнуются о пустых блоках кода. Если вам нужно или хотите вернуться к чему-то позже, используйте комментарии TODO. Они помогают вам помнить, и пусть другие знают, что что-то недостроено.

ответил JimmyJames 28 PMpThu, 28 Apr 2016 19:44:19 +030044Thursday 2016, 19:44:19
6

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

Комментарии в коде аналогичны - у вас должно быть минимальное количество комментариев, необходимых для понимания и использования кода. Если другие разработчики (включая вы , если вы вернетесь к своему собственному коду, не трогая его в течение 6 месяцев) не могут понять ваш код, потому что он недостаточно прокомментирован - чем у вас слишком мало комментариев , Если у вас слишком много комментариев, то по определению у вас есть комментарии, которые не нужны для понимания и /или использования кода. Эти комментарии тратят впустую ваше время на их запись, тратя время на то, чтобы прочитать их, и тратить время на поддержку тех, кто должен поддерживать их (или подвергать риску комментарии, выходящие из синхронизации с кодом).

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

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

def distance(x1, y1, x2, y2):
    return sqrt(  # root of the sum of the squares
        (x2 - x1) * (x2 - x1) +  # distance on the X axis
        (y2 - y1) * (y2 - y1))  # distance on the Y axis

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

Теперь давайте реорганизуем его для документа:

def distance(x1, y1, x2, y2):
    delta_x = x2 - x1
    delta_x_squared = delta_x * delta_x

    delta_y = y2 - y1
    delta_y_squared = delta_y * delta_y

    sum_of_squares = delta_x_squared + delta_y_squared

    return sqrt(sum_of_squares)

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

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

ответил Idan Arye 28 PMpThu, 28 Apr 2016 20:17:34 +030017Thursday 2016, 20:17:34
1
//Thoughts about code with too many comments
//I will give a reason to avoid using too many comments
//My reasoning will relate to the size of the source code
//I will also mention the need to update comments
//http://programmers.stackexchange.com/questions/317055/how-much-commenting-is-better-for-coding
// - user2023861
Here are my thoughts about code with too many comments

//checking if comments restate code
If you include comments that restate what your code is doing 

    //The size of the code will double
    Your code will double in size

    //code changes require comment changes
    When your code changes, your comments will also need to change

    //the code maintainer won't trust the comments and will ignore them
    This breaks the trust that a code maintainer may have in the comments

//The end of my hypotheical scenario
End if
ответил user2023861 29 PMpFri, 29 Apr 2016 21:01:12 +030001Friday 2016, 21:01:12
1

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

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

ответил Mike Dunlavey 29 PMpFri, 29 Apr 2016 23:47:10 +030047Friday 2016, 23:47:10
0

На самом деле «Насколько лучше комментирование [...]» - это неправильный вопрос. Правильный вопрос: «Какие комментарии хороши и какие комментарии плохи?»

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

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

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

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

С другой стороны, хорошие комментарии включают в себя информацию not , переданную самим кодом. И чем быстрее они находят свою точку зрения, тем лучше. Примеры включают:

  • Комментарии, описывающие предполагаемые шаблоны использования для кода.

  • Комментарии, описывающие архитектурные структуры, которые слишком велики для быстрого вывода из самого кода.

  • Комментарии, описывающие, почему код делает то, что он делает. Например, если код работает с ошибкой компилятора, нехорошо, если каждый человек, касающийся кода, сначала рефакторизует прорыв из кода, только чтобы понять, что этот рывок необходим, чтобы избежать запуска internal compiler error

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

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

ответил cmaster 30 AMpSat, 30 Apr 2016 01:29:11 +030029Saturday 2016, 01:29:11

Похожие вопросы

Популярные теги

security × 330linux × 316macos × 2827 × 268performance × 244command-line × 241sql-server × 235joomla-3.x × 222java × 189c++ × 186windows × 180cisco × 168bash × 158c# × 142gmail × 139arduino-uno × 139javascript × 134ssh × 133seo × 132mysql × 132