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

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

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

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

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

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

index.js:24
  throw err;
  ^
Error: Could not find config
  at ...

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

Когда это появилось для меня [да — мне удалось запустить его один раз во время разработки, забыв включить файл конфигурации, который я сам сделал обязательным…], меня поразило, что это был действительно плохой опыт.

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

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

This Error is thrown by the node-server module.
-----------------------------------------------

Здесь node-server — это имя, которое появляется в package.json для этого проекта. Упростите работу разработчика; дайте им имя, которое они могут выбрать из своих зависимостей.

Затем уделите внимание удобочитаемому сообщению об ошибке. Если ваше приложение не выдает удобочитаемые сообщения об ошибках, исправьте это в первую очередь!

Missing config file in config/node-server/server.js

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

Please create the config file at the expected path. Refer to the Github repository blah/node-server for format and configuration options.

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

If you have followed this resolution step and you are still seeing an error, please file an issue on the node-server repository:
_URL_TO_REPOSITORY_ISSUES_PAGE_HERE_

Затем завершите все, не скрывая никакой полезной информации, предоставленной исходной ошибкой, — отбросьте полную трассировку стека последней:

/Users/dstevensio/ws/node-server/lib/config-loader:58
  throw serverConfigError

Контекстное именование ссылок на ошибки также помогает — здесь, при создании обратного вызова для запуска сервера, я использовал serverConfigError, а не просто err, так что вывод трассировки стека более информативен. осмысленный.

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

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