Сообщение об ошибке, от которого не горит

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

Сижу, значит, программирую, внезапно консоль заливает красным, и вылезает вот это:

Uncaught Error: Bad dependency path or symbol.
  // стектрейс из скомпилированного (!) кода...
  // стектрейс из внутренних библиотечных функций...
  //
  // скомпилированного... напомню, это dev-режим.

Да, это сообщение об ошибке.
Да, это всё сообщение.
И да, это плохое сообщение.

Дальше — простыня, почему оно плохое.

Как надо

Хорошее сообщение об ошибке следует двум главным принципам:

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

Из этих принципов я бы вывел 4 правила, что хорошее сообщение:

Говорит, что именно сломалось — какой модуль, функция и т. д.
Где именно сломалось — как ошибку найти.
Почему оно сломалось — как ошибку воспроизвести, что не сходится.
Как это починить — что на что заменить, чтобы заработало.

Говорит, что именно сломалось

— Ваше приложение не работает.
— Да, но почему?
— Потому что оно сломалось ¯\_(ツ)_/¯

То, что приложение не работает, я уже знаю — оно, блин, не работает. Мне как бы нужно понять из-за чего.

В ошибке выше, вроде, даже написано, что сломалось, вот — Bad dependency path or symbol. Но что именно-то: bad dependency path или bad symbol? Если символ, то какой? Если путь до зависимости, то до какой?

Почему бы, например, не сделать так?

Bad dependency path.
  Cannot find module "superModule".

Указывает, где сломалось

Чтобы что-то починить, надо исправить код. Чтобы в коде что-то исправить, надо найти, что
— Ваш Кэп

В эпоху до сборки фронтенда (помните, IE7, FTP, jQuery, эх!..) всё было просто. Стектрейс сам говорил, на какой строке беда. Сейчас браузерный стектрейс может не помочь.

Указывать на ошибку в скомпилированном (а тем более минифицированном) коде — бесполезно чуть более, чем полностью. Рассказывать надо об исходниках: модуль, функция, строка, символ — вот что нужно, чтобы быстро найти ошибку.

Bad dependency path at line 42, character 88 in "entryPoint.js".
  Cannot find module "superModule".

Объясняет, почему оно сломалось

С любовью, вечно ваш “undefined is not a function”

Да, если произошла низкоуровневая ошибка, синтаксическая например, надо об этом написать. Но undefined is not whatever как бы так сказать, is not enough. Ткните, пожалуйста, носом в то место, которое не работает: в поле объекта, название функции, метода.

Если произошла высокоуровневая ошибка, объясните, что именно пошло не так: почему здесь нужен другой аргумент, зачем указывать абсолютный путь и т.д. Дайте ссылку на документацию, это полезно. Даже если документация скудная. Даже если API в ней не нуждается.

Bad dependency path at line 42, character 88 in "entryPoint.js".
  Cannot find module "superModule".
  Expected one of extensions: "js", "jsx", "ts", "tsx", "mjs", but tried to import "".

Инструктирует, как починить

— Хм, а как это починить?
— Ну вы держитесь здесь, вам всего доброго, хорошего настроения и здоровья

Допустим, стало понятно, что именно сломалось. Если сообщение об ошибке рассказывает, как чинить — это прекрасно.

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

Ещё один хороший способ — показать примеры работы функции, что она вернёт при каких аргументах. Так делает Lodash в jsdoc и многие модули Python в docstring.

Да, это запарно. Но разработчики скажут спасибо.

Bad dependency at line 42, character 88 in "entryPoint.js".
  Cannot find module "superModule".
  Expected one of extensions: "js", "jsx", "ts", "tsx", "mjs", but tried to import "".
  Check your import extension and make sure file exists.
  Note that this lib supports only imports with direct link to a file with its extension.

Опирается на факт, что всё горит

Тут всё как у Ситника в докладе о продвижении проектов.

Разработчики не читают логи с ошибками в кресле под уютным пледиком. Дайте нужное, кратко, точно, с примерами.

Заботится о разработчике

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

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

Ну и вообще…

Это всё — просто эффективная коммуникация и желание помочь. Ильяхов в Правилах деловой переписки писал подобное. А сообщение об ошибке — чем не переписка?

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