UserStory — держим логи клиентсайда в тепле, то есть в комментариях

Сегодня хочу рассказать про написанную мной библиотеку UserStory. Она преобразует комментарии в js-коде в вызовы консольного логгера. Разработчик сам решает, какие сообщения показывать в текущий момент прямо из консоли. У логов есть иерархические метки, что крайне полезно.

Возможности и преимущества

Иерархия логгеров

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

Например, рассмотрим группу меток: @news, @news.render, @news.render.getContext и @news.add. Вот как можно вывести все события по новостям, но исключить всё, что связано с их отрисовкой. Набираем в консоли:

UserStory.on('news');
UserStory.off('news.render');

Теперь в консоли будут появляться логи с метками news и news.add. Одному сообщению можно присвоить несколько меток. Состояние «предпочтений» сохраняется в localStorage.

Комменты и дебаг одновременно

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

Если вдруг появится задача починить баг на проекте, которым давно не занимался, я сначала выполню в консоли UserStory.on('*'), затем воспроизведу баг и, наконец, увижу в консоли, что происходит. Вероятно, это сэкономит время погружения в проект. Также это поможет и новым разработчикам.

Частая проблема разработки — наличие в коде ручных вызовов логгера, например, сonsole.log() или mySuperLog(), что мешает чтению кода. Комментарии же лежат на отдельном уровне восприятия, в IDE обычно отображаются ненавязчиво.

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

Как подключить

Во-первых, устанавливаем библиотеку:

npm install user-story

Чтобы UserStory заработал, надо перегнать js-файл через скрипт библиотеки:

cat input.js | ./node_modules/user-story/bin/us > output.js

Если используется django и django-compressor:

COMPRESS_PRECOMPILERS.append(
    ('text/javascript', 'node %s' % os.path.join(ROOT_PATH, '/node_modules/user-story/bin/us')),
)

Затем подключить клиентскую часть:

bower install UserStory

<script type="text/javascript" src="UserStory.js"></script>

Другой метод подключения — через адаптер к гранту grunt-user-story.

Гитхаб-репозиторий

PS. Библиотека находится в стадии прототипа, но уже активно нами применяется на наших проектах.