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

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

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

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

Зачарованный лес. Вы хотите, чтобы не вмешиваться в него.

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

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

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

С сегодняшними достижениями в распределенных технологиях система редко будет жить в своих собственных помещениях и никогда не выходить на улицу, чтобы поговорить со своими соседями. Это довольно редко. Вместо этого система будет жить в большой общедоступной сети, известной как Интернет. А раз система живет в Интернете, то система просто попала в заколдованный лес. Все может случиться. Все произойдет. Комментарии в коде не очень полезны, если система динамична; когда система жива.

Вот тут-то и появляется логирование.

Ведение журнала — это канал связи, который система использует для передачи своих взаимодействий и состояния из своего цифрового мира в наш: реальный мир. В нашем мире у нас есть все, чтобы помочь системе любым возможным способом. Но если система не разговаривает с нами и не сообщает нам, как она работает и что она делает, мы остаемся в неведении. Так и система. Система нуждается в нас, чтобы обеспечить ей хорошую жизнь в цифровом мире. Для этого система должна говорить с нами. Почти так же, как родитель просит своего ребенка или подростка поделиться некоторой информацией об их жизни. Или, еще лучше, как врач, который спрашивает пациента, как у него дела, чтобы улучшить его жизнь.

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

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

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

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

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

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

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

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

Поэтому в следующий раз, когда вы будете писать код для программного обеспечения, признайте тот факт, что с системой произойдет что-то не так. Ваш код может быть идеальным, но среда, в которой вы кодируете, — нет. Электричество и напряжение не всегда постоянны. Жесткие диски могут выйти из строя. Зависимые компоненты могут не отвечать. Интернет настолько хаотичен, что любой может догадаться, почему могла произойти ошибка.

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

Дорога, ведущая вдаль из заколдованного леса.