Андруша пишет код

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

А у меня в мозгу есть суровый баг. Зачастую я не вижу связи между задачами и возможностями инструмента, даже если я знаю и про возможности, и про то как решаются задачи.
И я даже могу сходу привести пример подобного: зачем нужны inlineSnapshot в jest/vitest? Есть идеи? Вот я знал о наличии подобных штук, но никогда не применял, так как не видел смысла. И даже более, я начал в штыки воспринимать снепшоты, так как куча людей начали их использовать для тестирования интерфейсов.

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

Пишите в документации не только "что умеет", но и "зачем умеет". Это очень сильно упрощает жизнь.

www.tgoop.com/xavescor_code/222

1.3K viewsNov 16, 2024 at 14:25

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

А у меня в мозгу есть суровый баг. Зачастую я не вижу связи между задачами и возможностями инструмента, даже если я знаю и про возможности, и про то как решаются задачи.
И я даже могу сходу привести пример подобного: зачем нужны inlineSnapshot в jest/vitest? Есть идеи? Вот я знал о наличии подобных штук, но никогда не применял, так как не видел смысла. И даже более, я начал в штыки воспринимать снепшоты, так как куча людей начали их использовать для тестирования интерфейсов.

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

Пишите в документации не только "что умеет", но и "зачем умеет". Это очень сильно упрощает жизнь.

BY Андруша пишет код