Прежде всего, в этом вопросе я бы хотел избежать полемики о том, является ли комментирование исходного кода хорошим или плохим. Я просто пытаюсь понять, что люди имеют в виду, когда говорят о комментариях, которые говорят вам, ПОЧЕМУ, ЧТО или КАК.
Мы часто видим рекомендации типа «Комментарии должны указывать, ПОЧЕМУ; сам код должен указывать, КАК». Легко согласиться с утверждением на абстрактном уровне. Однако люди обычно отбрасывают это как догму и покидают комнату без дальнейших объяснений. Я видел, как это используется в столь разных местах и контекстах, что кажется, что люди могут прийти к единому мнению по ключевой фразе, но, похоже, они говорят о разных вещах полностью.
Итак, вернемся к вопросу: если комментарии должны сказать вам, ПОЧЕМУ, что это за ПОЧЕМУ мы говорим? Это причина, почему этот кусок кода существует в первую очередь? Это то, что должен делать этот кусок кода? Я был бы очень признателен, если бы кто-то мог дать четкое объяснение, а затем добавить несколько хороших примеров (плохие примеры на самом деле не нужны, но вы можете добавить их для контраста).
Есть много вопросов о том, являются ли комментарии хорошими или плохими, но никто не отвечает на конкретный вопрос о том, что являются хорошими примерами комментариев, которые говорят вам, ПОЧЕМУ.
There are many questions on whether comments are good or bad, but no one that addresses the specific question of what are good examples of comments that tell you WHY.
Если все приводят действительный пример, то все они являются правильными ответами. Формат этого веб-сайта облегчает процесс вопросов и ответов, когда не все ответы одинаковы.Ответы:
Наиболее распространенным и наиболее ярким примером являются комментарии вокруг различных обходных путей. Например этот:
Вы наверняка найдете больше примеров в источниках Git и Linux; оба проекта пытаются следовать этому правилу.
Я также рекомендую придерживаться этого правила еще более строго в журналах фиксации . Для комментариев кода может случиться так, что вы исправите код, но забудете обновить комментарий. С количеством кода в обычном проекте это гарантированно произойдет рано или поздно. С другой стороны, журнал фиксации привязан к конкретному изменению и может быть вызван с использованием функциональных возможностей «annotate» / «обвинить» системы контроля версий. Снова у Git и Linux есть несколько хороших примеров.
Посмотрите, например, на этот коммит . (не копировать здесь, это слишком долго). В нем четыре абзаца, занимающие почти всю страницу (и немного более экранные), в которых описывается, что именно было не так, и почему это было неправильно, а затем происходит и изменяет все колоссальные строки SIX. Подобные комментарии они используют для двух целей:
(примечание: мне потребовалось не более 10 минут случайного просмотра репозитория git, чтобы придумать эти два примера, так что было бы легко найти больше там)
источник
Комментарий, который говорит вам, почему объясняет причину кода - например:
Комментарий, который говорит вам, как объясняет, что делает код.
Разница в том, что сопровождающий может взглянуть на первый и сказать: «О, так что это может быть устаревшим!» Во втором случае у указанного сопровождающего есть комментарий, который не говорит вам ничего, что сам код не раскрывает (при условии хороших имен переменных).
Вот реальный пример комментария почему, из некоторого кода iOS, над которым я работал, где нам нужно было получить адрес шлюза (или разумное предположение для него). Я мог бы просто оставить комментарии, в которых говорилось что-то вроде «Инициализировать сокет получения», но это сообщало бы только сопровождающему (или будущему мне) о том, что происходит, а не о том, почему мне пришлось сделать этот странный клудж, чтобы получить адрес шлюза в первое место.
источник
Я хотел бы начать свой ответ с цитатой из Джефф Этвуд в своем блоге кодекса Сообщает вам , как, Комментарии Скажите , почему :
Он также заявляет, что:
Я полностью согласен, и в этот момент я должен добавить, что прежде чем я смогу сделать код как можно более простым, я заставляю код работать, а затем начинаю рефакторинг. Поэтому во время первого запуска перед рефакторингом добавление комментариев очень помогает.
Например, при использовании 3-х вложенных циклов с 2-х мерными хеш-таблицами для заполнения таблицы дней недели при разборе данных очень легко потерять отслеживание того, что было сделано кем-то или даже вами, если не смотреть в течение нескольких недель и внезапно провести рефакторинг.
Верхний пример является примером того, как 3 вложенных цикла будут работать до рефакторинга.
Кроме того, объяснение некоторых условий ветвления может помочь понять код намного лучше с тем, что вы думали в процессе:
Даже простой и очевидный код хорошо работает с комментариями. Просто чтобы сделать вещи немного более очевидными, более ясными или понятными для коллег и даже для вас самих в поддержке программного обеспечения.
Конечно, xp утверждает, что имеет код, который самоочевиден, но больно ли однострочный комментарий?
Я также считаю, что следующие правила из этого блога очень полезны:
Любой, кто должен вернуться в свой собственный код или кто-то другой, или даже старый код, знает, что это может быть головной болью. Поэтому вместо того, чтобы быть ленивым или пытаться быть убер-кодером, не комментируя что-либо или очень мало, почему бы не сделать свой собственный или какой-то плохой урод, который должен поддерживать ваш код, будущей жизнью намного проще, следуя приведенным правилам.
Кроме того, многие сделанные решения по программам ставятся под сомнение во время проверок, и не всегда понятно, почему некоторые части были написаны так, как они были, даже если некоторые разделы кода жизненно важны для работы программы из-за серьезной ошибки, обнаруженной, поскольку код использовался в течение многих лет. , Таким образом, чтобы не утомлять вас всех полностью с помощью тулда, закройте последнюю цитату из acmqueue :
источник
int directionCode = (x > oldX) ? DIRECTIONCODE_RIGHT : (x > oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;
содержит ошибку. Конечно, должно быть... (x < oldX) ? DIRECTIONCODE_LEFT : DIRECTIONCODE_NONE;
. Хорошие идеи комментариев - плохой код.Я склонен сводить комментарии либо к ссылкам, где определенная функциональность / код объясняется более подробно, либо к объяснению, почему выбран определенный способ программирования.
Учитывая, что другие программисты со схожими навыками используют или читают ваш код, важно прокомментировать, если вы используете другой способ достижения чего-либо. Таким образом, вы можете объяснить в комментарии, почему вы выбрали этот путь.
Например, если вы можете использовать два разных датчика на устройстве Android, и один из них не соответствует вашим потребностям, вы можете объяснить в комментарии, почему вы выбрали другой.
Таким образом, «почему» должно дать обоснование вашего выбора.
источник
Комментарии должны указывать на то, что код не делает, не обязательно разделять на WHY , HOW или WHAT . Если у вас хорошие имена и хорошо разграниченные функции, вполне возможно, что код точно скажет вам, что происходит. Например:
Этот код действительно не нуждается в комментариях. Имена функций и типов облегчают понимание.
Иногда, однако, может быть трудно или невозможно действительно создать свободный код, подобный приведенному выше. Например, следующий фрагмент кода предназначен для поиска статистически случайной точки на сфере. Математика довольно непрозрачна, поэтому комментарий со ссылкой на объяснение должен помочь понять, КАК это работает. Это можно обернуть в функцию, чтобы сказать, ЧТО она делает, не нуждаясь в комментариях, если это необходимо более одного раза, в противном случае заголовок ссылки также помогает в этом отделе.
Другой пример, когда комментарии говорят вам, что код не делает, это для объяснения решения. В следующем примере код не блокирует не-локальную переменную внутри многопоточного фрагмента кода. Для этого есть причина, и в комментарии объясняется ПОЧЕМУ . Без комментария это можно считать ошибкой или просто не заметить.
Возможно, было бы лучше сказать, почему в первую очередь случайный объект не создается внутри параллельного цикла. Если нет причин, это также может заставить кого-то прийти и понять, что вся идея глупа и является хорошим местом для рефакторинга.
источник
WriteText
а не//
?Может быть полезно распознать различные виды «почему», в частности:
Причины, по которым код, который кажется слишком сложным, не будут работать, если его упростить (например, может показаться, что для обеспечения правильной работы кода в некоторых случаях может потребоваться избыточное приведение типа)
Причины, по которым какая-то конкретная простая операция, которая выглядит опасной, на самом деле безопасна (например, «Наша подпрограмма выборки данных сообщит, что элемент-пустышка после последнего будет меньше, чем что-либо еще, а элемент после этого будет больше; любой элемент, который должен сортироваться» перед другим, в последовательной восходящей или нисходящей последовательности, будет следовать по крайней мере еще один (возможно, фиктивный) элемент ").
Во многих случаях комментарий второго типа в одной части кода может «совпадать» с комментарием первого типа в другом (например, «хотя может показаться, что эта последовательность операций может быть упрощена, подпрограмма Фитца опирается на Wongle не будет Woozled до тех пор, пока Bandersnatch не был Blarped. ")
источник
Не забывайте, что если вы пишете программу, вы не просто набираете текст произвольно, вы делаете это, потому что у вас есть модель того, что вы хотите , будь то в официальном документе или просто в вашей голове. Вещи в вашей голове настолько же реальны, как и программное обеспечение / данные на компьютере (и с такой же вероятностью содержат ошибки).
Кто-то, читающий ваш код, может не иметь этой модели в своей голове, поэтому комментарии могут служить для того, чтобы рассказать им, что это за модель и как код связан с ней. Я думаю, что именно это означает «почему». Конечно, хорошо сделать сам код как можно более понятным, но этого не всегда достаточно. Пример:
Кроме того, модель со временем меняется, и эти изменения должны быть перенесены в код. Поэтому в комментариях нужно не только сказать «почему» что-то в коде, но так же важно, как это изменить в ответ на ожидаемые изменения модели. Пример:
Я думаю, что целью комментариев иногда пренебрегают.
источник
Не все мои комментарии относятся к типу «почему», но многие из них.
Это примеры из одного (Delphi) исходного файла:
Обратите внимание, что (мое), почему комментарии обычно предшествуют коду, который собирается это сделать (следовательно, заканчиваются двоеточием).
У меня есть некоторые комментарии, объясняющие только то, что происходит, например, когда у процесса есть много шагов, которые имеют логическую группировку (и код не подвергается рефакторингу, чтобы показать это автоматически), я буду комментировать как:
источник
Я понимаю ПОЧЕМУ как причину, по которой вы делаете что-то странным или, возможно, нелогичным образом, в силу конкретных обстоятельств, требующих этого. Как можно увидеть в самом коде, независимо от того , как странно, даже если код не имеет «смысл». Что , вероятно , лучше всего сказано в начале документации класса / функции. Таким образом, у вас остается добавление ПОЧЕМУ , где вы объясняете все, что не включено в КАК и ЧТО, и специфические способы, которые вы должны использовать по причинам, которые вы не можете контролировать.
Конечно, это не всегда так, за пределами земли единорогов и радуг ...
КАК:
ЧТО:
ПОЧЕМУ:
источник
critters.dance()
, тогда комментарий просто повторяет очевидное, и «Мы не могли заставить его работать любым другим способом, который мы пробовали», совершенно бесполезно. Кроме того, высказывание «мы будем вызывать метод для каждого объекта» повторяет то, что код очень четко говорит.Я научился ВСЕГДА писать комментарии в заголовочных файлах C ++ (поскольку не всегда понятно, ЧТО делает функция, даже если имя дает хороший совет), особенно если вы передаете API другим разработчикам или используете инструмент для autodoc, такой как doxygen.
Так что для меня типичный комментарий выглядит примерно так
Единственный раз, когда я использовал комментарии ПОЧЕМУ, это вещи, которые трудно понять, а иногда даже программисту, например, «НЕ ПРИКАСАЙТЕСЬ К ЭТОМУ!
Обходы, хаки и странное поведение соответствуют критериям WHY в моих глазах ...
Очень хороший и даже веселый пример - это «обходной путь» для некоторого испорченного кода, написанного кем-то по имени Ричард, кто-то другой обернул его и объяснил, почему в комментариях ... https://stackoverflow.com/a/184673/979785
К сожалению, есть довольно много случаев, когда вы вынуждены обернуть быка ****, потому что вы не можете прикоснуться к оригиналу, либо потому, что «так было всегда», либо у вас нет доступа, либо ... ну, вы не хватает времени, чтобы починить оригинал с той целью, которая на самом деле не соответствует накладным расходам.
источник
documentation
тег вызывает сожаление, но все же не относится к вопросу).Код должен указывать план выполнения. Таким образом, программа-последователь (или компилятор) может выяснить, что и как делать. То, что разбито на шаги, которым может следовать подписчик программы. Примитивные шаги как.
Цель кодера - другое дело. В простом, понятном и понятном коде цель очевидна. Любой достаточно опытный человек-читатель придет к цели блока кода, просто прочитав код. Большая часть кода должна читаться следующим образом.
Иногда связь между намерением и планом неясна. Код показывает, что и как, но не почему. Вот когда комментарии, раскрывающие намерения, стоят того. Цель программиста - почему.
источник
Имея эту проблему прямо сейчас, мы рассмотрим хранимые процедуры и представления относительно сложной и несколько запутанной модели данных.
Мы (многочисленные) составили выборки типа «Случай, когда x.account не равен нулю и x.address in (выберите адрес из fedex), затем x.account иначе y.account end» повсюду, и производительность ожидается, хотя времени нет все, чтобы прочитать весь исходный код. И этот пример вроде как имеет смысл, но он все еще непостижим.
Комментарии, объясняющие, почему, если в fedex тогда x, а если нет, то y - проливает свет на всю систему, и когда мы читаем достаточно их, мы начинаем понимать это. И это слишком упрощенно, и есть сотни или тысячи подобных утверждений. Мое сердце горячо пылает по отношению к тому, кем был добрый разработчик из 2007 года, кто вставил те, почему.
Так что, да, сложные извилистые модели данных, волосатые узоры и хранимые процедуры с несколькими правильно названными путями, пожалуйста, ради любви Б-га, объясните нам, почему.
источник
Я только что написал этот комментарий; это конкретный пример объяснения, почему строка кода такая, какая она есть, и, в частности, почему я ее изменил.
Метод проверяет сохраненные данные и оценивает, завершены ли они до сегодняшнего дня с одной стороны и до даты начала с другой стороны.
Как вы, вероятно, можете догадаться, оператор «больше» был больше или равен. Комментарий объясняет, почему старое значение имеет смысл и почему новое значение лучше. Если кто-нибудь посмотрит на это в будущем, он увидит, что использование «>» - это не упущение, а оптимизация. Затем они могут изменить его или оставить, исходя из необходимости в то время.
источник