Сообщение журнала — это исполняемый код и комментарий

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

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

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

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

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

Ниже приведены два листинга кода, один из которых использует комментарий в коде, а другой — протоколирование, чтобы выразить то же мнение разработчикам, поддерживающим этот код в будущем. В обоих случаях документально подтвержденное соображение бизнес-логики заключается в том, что Суперкубок Национальной футбольной лиги (НФЛ) в 2016 году (выигранный « Денвер Бронкос» ) не был назван в соответствии с традиционным соглашением о присвоении имен римскими цифрами . Вместо того, чтобы называться «L», как предполагалось на основе более ранних Суперкубков, этот был назван «50». Это надуманный пример типа правила бизнес-логики, которое часто выражается в виде комментария в коде. Строка 10 — фокус каждого списка кода здесь.

Реализации для методов getSuperBowlYearFromNumber(int) и getDecimalNumber(String) здесь не показаны, поскольку они не важны для этого обсуждения. Здесь важно то, что «L» не является действительным номером Суперкубка, поэтому при определении года проведения Суперкубка необходимо использовать «50» вместо «L». Разработчик, незнакомый с соглашением об именах Суперкубка или НФЛ или его Суперкубка 2016 года, нуждается в комментариях, чтобы понять, почему один Суперкубок рассматривается по-другому, чем другие.

В качестве примечания и разговора о римских цифрах, немного удивительно, сколько примеров кода Java есть в сети для преобразования между римскими цифрами и целым числом на основе десятичных чисел. Некоторые из них включают Преобразование римских цифр в десятичную , Преобразование римских цифр в десятичную от 1 до 3999 , Преобразование римских чисел в десятичное с использованием Java , Преобразование римских чисел в десятичное в java и Как преобразовать римское число в целое число . Я подозреваю, что есть много проблем с домашним заданием, вдохновляющих множество примеров кода.

Алексей недавно опубликовал сообщение в блоге: « Замените комментарии TODO в своем коде на сообщения журнала ПРЕДУПРЕЖДЕНИЕ, может быть? ”, В котором он заявляет, что начал писать сообщения журнала предупреждений и уровней ошибок в ситуациях, в которых он ранее писал комментарии“ TODO ”. Это более конкретный и более очевидный пример использования сообщений журнала вместо комментариев. В случае Алексея он делал это, потому что он понял, что «всегда забывает о» комментариях «TODO», и они «редко бывают найдены и почти никогда не исправляются». Алексей делает вывод: «Вот почему я советую вам попробовать этот подход с записью ваших комментариев, ваших мыслей и даже ваших сомнений в журналы: это поможет вам и даже сможет развлечь вас и ваших коллег!»

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