Комментарии 40
В целом, согласен, только вот пример выбран неудачный:
// Поиск по формату: kk:mm:ss EEE. MMM dd. yyyy
сonst timeMatcher = new RegExp('\\d*:\\d*:\\d* \\w*. \\w* \\d*. \\d*');комментарий и код вообще разные
Сложными регулярками вообще лучше не упарываться, тогда и комментировать их не придется.
А почему разные-то? Регулярка распарсит формат из комментария, всё, кажется, нормально.
Регулярка разрешит и много чего другого, это плохая, слишком общая регулярка, факт. Но вполне можно представить что какой-то джун написал именно эту регулярку под именно этот коммент. Что «совсем разные» вроде непохоже.
Комментарий – признак неудачи.
У вас не получилось написать код так, чтобы его можно было понять без комментариев.
Проблема в том, что комментарии обычно пишет автор кода. Ему код понятен - он же его написал. Точнее, в данный момент понятен.
А будет ли он понятен другим? Или ему же через пару лет?
На мой взгляд, лучшая практика - писать сначала комментарии, а потом код. Тогда комментироваться будет именно смысл кода, а не его реализация.
Даешь comment driven development! :)
Видимо, человек читает любые Regex выражения, как родной язык. Завидую.
Смысл того, что здесь будет сделано.
"копетанить"?
Будет дублировать смысл, который и без того хорошо читается по коду реализации. В статье это отражено разделом «Избыточные комментарии».
Не совсем. Из кода можно понять "что делается". Зачем - не всегда.
Кроме того, вопрос уровня восприятия. Если на понимание, что делает код надо потратить 15 минут, а на чтение комментария - 5 секунд, то его явно стоит написать. Как пример - те же регулярные выражения.
Как пример — те же регулярные выражения.Разве имя функции
parseDateTime или переменная с регуляркой identifierFormat не отвечают на вопрос: «Зачем?»?"Зачем" - в смысле "для чего". Например, "Ищем минимум". Код, как раз, отвечает на вопрос "как".
Разве имя функции...
Хорошо, когда случай такой простой. А если посложнее: "ищем почтовые адреса в нашем домене, начинающиеся с цифры или подчеркивания"?
По поводу понятности имен - см. мой первый комментарий.
А если посложнее: «ищем почтовые адреса в нашем домене, начинающиеся с цифры или подчеркивания»?Этот коммент как раз отвечает на вопрос: «Каким образом?» (реализация) и совершенно не дает ответа на: «Зачем?».
Здесь должно быть что-то значимое с точки зрения бизнес-логики, вроде: «Поиск адресов региональных подразделений», не расрывая нюансов реализации. А это уже легко выносится в имя переменной/функции.
Это может быть вопрос "зачем", зависит от степени детализации. Т.е., конечно, с точки зрения бизнеса это скорее звучало бы как "хотим найти учетные записи, принадлежащие определенной категории клиентов". Но иногда почтовые адреса с цифры и подчеркивания реально должны хендлиться отдельно...
Где же тут "каким образом"? Мы можем использовать регулярные выраженя, можем написать конечный автомат, можем просто искать подстроки и потом обрабатывать результат - вариантов масса.
«Поиск адресов региональных подразделений» ... легко выносится в имя переменной/функции.
"Поиск адресов отделов рекламаций закрытых региональных подразделений в старом формате" - легко выносится?
И, кстати, не всегда можно выделить переменную/функцию. Переменных может быть несколько. Код может использовать/изменять много переменных из окружения, которые при выделении функции придется передавать через параметры. То есть, выделить, конечно, можно, но написать комментарий может быть эффективнее.
Где же тут «каким образом»? Мы можем использовать регулярные выраженя, можем написать конечный автомат
Конкретный формат — это часть реализации, равно как и механизм его поиска.
«Поиск адресов отделов рекламаций закрытых региональных подразделений в старом формате» — легко выносится?
А в чем проблема? Похоже на параметры.
А будет ли он понятен другим? Или ему же через пару лет?
Для этого как раз и существует система ревью, и такой же вопрос можно задать к комментарию: A будет ли комментарий понятен другим? Или будет комментарий акутальным через пару лет?
На мой взгляд, лучшая практика - писать сначала комментарии, а потом код.
Как раз в таких случаях чаще всего забывают актуализировать комментарии, когда во время разработки решили внезапно поменять реализацию.
Не знаю, как Вы можете определить заранее, нужен ли комментарий к коду или нет, не написав даже строчки кода)
По-моему, идеальный вариант - это самодокументированный код + комментарий с идеей реализации, но только если код действительно сложен или специфичен.
Журнальные комментарии, ссылки на авторов
Название главы не соответствует содержанию. :-)
Есть, кстати, возражение на "На самом деле, современные системы Git и IDE позволяют узнать, кем и в рамках какой задачи изменён код.". Это всё ещё далеко не везде так.
Мы с коллегой буквально на прошлой неделе столкнулись с проблемой: из сторонней организации прислали код на VBA, в котором реализован некий метод монотонной интерполяции. Он похож на Fritsch-Carlson, но не совсем то (возможно Fritsch-Butland). И вот будь там ссылка на статью, которая взята за основу, нам бы было значительно проще.
И вот будь там ссылка на статью, которая взята за основу, нам бы было значительно проще.
Ох, не факт. Вспоминаю 2 случая.
1. Необходимо было реализовать расчёт коэффициента сжимаемости газа на С. Купила наша организация соответствующий ГОСТ (вроде, 30319.2-96), в котором расписаны различные методы, приведены формулы и примеры кода на фортране с результатами. Написал программу, сверяю с примерами — не сходится. Скачал стороннее приложение — результаты сходятся (с ГОСТ). В итоге выяснилось, что в одной из формул нашей копии ГОСТа была ошибка. Кстати, если кому интересно, в новом ГОСТ (кажется, 30319.2-2015) коэффициент сжимаемости — это величина, которая в предыдущем ГОСТе называлась фактором сжимаемости; а фактор сжимаемости в новом ГОСТе отсутствует.
2. Расчёт расхода газа через критические сопла. В документах на сопла дана ссылка на методику расчёта некоторых параметров. Вот только проблема: в бесплатном доступе эту публикацию найти не удалось. Пришлось запрашивать пример расчётов, искать самостоятельно альтернативные публикации и т.д.
Вывод: простого указания на источник не всегда достаточно, в идеале — прикладывать сам источник (если это законно, конечно).
Во-первых, мне кажется Вы неправильно поняли, что имеется в виду под термином журнальные комментарии. Ссылка на авторов - это не то же самое, что список используемой литературы или список источников к дипломной или курсовой работе. Это просто комментарий, что данные правки делал Вася Пупкин 31.12.2021 в рамках задачи TSK-123, вряд ли бы это Вам помогло понять, какой алгоритм реализован в данном куске кода. А ссылку на статью можно отнести скорее к информативным комментариям или чему-то подобному.
Во-вторых, если вы работаете с кодом без использования системы контроля версий, то мне кажется, у Вас серьёзные проблемы. Но даже если бы у вас была историй изменений в git к коду на VBA, она бы вам вряд ли помогла в Вашей ситуации.
// Для дополнительных задач требуется добавлять префикс перед идентификатором, чтобы он не совпадал с каким-либо из id выездовПочему бы не заложить это поведение в сам тип?
orderStateDTO.setOrderId(«f_» + additionalTask.getId());
Хороший код в комментариях не нуждаеться.
Нормальным считаеться комментирование публичных классов, методов и их параметров. Всё остальное хлам и каша.
Комментарий в середине метода самое большое днище, писать надо так что-бы понятно.
Не писать c = a*b, а нормальное totalElementCount = rowCount × rowCapacity. И тогда не надо писать коммент что это и откуда.
Переменные должны отражать своё назначение.
Методы должны соответствовать тому что делают и это должно быть понятно по имени метода.
И всё)))) Чистый код, минимум комментов = прекрасное далёко.
Это слишком упрощенный подход.
Безусловно, можно разбить код на методы, и каждый метод поименовать понятно.
Но это не избавляет от проблем понимания типа
- почему здесь используется такая формула, а не такая?
- зачем вы соединили методы именно таким образом?
- почему тут так все плохо? Или наоборот, хорошо?
- если надо изменить некий функционал, где именно надо изменить?
Автор статьи написал практически все по делу, чувствуется большой опыт.
Ох, спорно это. Я не уверен, что подобные проблемы должны решаться комментариями.
почему здесь используется такая формула, а не такая?
Вероятнее всего - так надо по тех.заданию. Если говорить не только о промышленном коде, а допустим о решении задач на литкоде, то там встречается ситуация когда задачу, которую вы решили подбором (написали бинпоиск), а потом видишь у соседа какую-то формулу - и не зная мат.часть ты никогда не поймёшь что это и почему так (вместо бинпоиска применили формулу Ньютона) если до этого не знаешь.
зачем вы соединили методы именно таким образом?
Не уверен, что правильно понял пример (приведите свой если не так понял), но по-моему это скорее вопрос, который решается изучением типовых паттернов программирования, а не написанием комментариев.
почему тут так все плохо? Или наоборот, хорошо?
Почему всё так плохо - писал новичок без надзора и ревью, либо жёсткий цейтнот "фича нужна вчера". Но непонятно ни то, нафига задаваться такими вопросами читаюему и нафига пишущему код об этом задумываться и подбирать комментарии. Иначе будут появляться комментарии вида "я пьян, поэтому тут г..но полное", а они мешают.
если надо изменить некий функционал, где именно надо изменить?
Ну это вообще вопрос на миллион. Человек пишущий код - должен думать о том, как решить текущую задачу, он понятия не имеет о будущих людях, кто будет этот код потом изменять и дополнять. Да, если у пишущего есть архитектурное мышление - он как правило будет писать код, который в некоторых пределах будет допускать расширение по типовым направлениям, но не всем. (Универсальной архитектуры подо всё нет; бесконечно универсальный код стоит бесконечно много).
Немножко юмора из личного опыта (комментарии в реальном Enterpsise-коде):
// Массив вместо ArrayList использован здесь просто из-за лени.
// Something about dark magic. Do not delete this emty "if", because it causes view invalidation.
(Моё любимое, for ever, судя по истории - коммент на месте удалённой строки кода) // Юра, извини.
понял галвное: нужно прочитать "Чистый код"
Я все понимаю, но скажите: почему в вашем коде имена методов на русском языке???
(имею ввиду рабочий код самого ДоксВижн)
Если нет корпоративного или иного стандарта, все остальные слова о комментариях - чистой воды вкусовщина. Каждый пишет то, что хочет и как хочет в процессе разработки. Потому что пишет в первую очередь - для себя. Сколько людей (и проектов) - столько и мнений, как именно лучше писать комментарии.
Есть стандарт и его требования - извольте исполнять. Собираешься делиться кодом - подумай об осмысленности и полезности комментариев для других. Все остальное обсуждать - бессмысленно.
Правила и рекомендации по комментированию в коде