Рефакторинг 031 - Удаление упс
11 августа 2025 г.Дайте пользователям помощь, а не путаницу
TL; DR: замените расплывчатые сообщения об ошибках на конкретную, действенную обратную связь, которая помогает пользователям решать проблемы.
Проблемы решаются 😔
- Пользовательская путаница и разочарование
- Не предоставляется действенное руководство
- Технический жаргон
- БедныйНеупомянутые ошибки
- БедныйUX
- Плохое восстановление ошибок
- НеполныйИнформация об ошибке
- Снижение доверия пользователей
- Общие сообщения
- Безмолвные неудачи
Связанный код запах 💨
https://hackernoon.com/how-to-find-the-shooky-parts-of-your-code-part-xx-we-have-переносится 100
https://hackernoon.com/how-to-find-the-shooky-parts-of-your-code-part-xxxiv
https://hackernoon.com/how-to-find-the-shooky-parts-of-your-code-part-xv
https://hackernoon.com/how-to-find-the-shooky-parts-of-your-code-part-vi-cmj31om
https://hackernoon.com/how-to-find-the-shooky-parts-of-your-code-part-xxvii
Шаги 👣
- Определите все общие сообщения об ошибках в вашей кодовой базе, которые используют такие термины, как «упс», «что -то пошло не так» или «произошла ошибка»
- Заменить общие сообщения на конкретные описания того, что произошло
- Добавьте действенное руководство сообщать пользователям, что они могут сделать, чтобы решить проблему
- Реализуйте надлежащую внутреннюю регистрацию для получения технических деталей для разработчиков
- Добавьте предупреждения о мониторингах, чтобы уведомить команду разработчиков, когда часто возникают ошибки
Пример кода 💻
До 🚨
function processPayment(paymentData) {
try {
// Too broad try catch
validatePayment(paymentData);
chargeCard(paymentData);
sendConfirmation(paymentData.email);
} catch (error) {
// Generic error message shown to user
return {
success: false,
userMessage: "Oops! Something went wrong. Please try again.",
error: error.message
};
}
}
function handleError(res, error) {
// Exposing HTTP 500 to users
res.status(500).json({
message: "Internal Server Error",
error: error.message
});
}
После 👉
function processPayment(paymentData) {
try {
validatePayment(paymentData);
// This catch is specific to payment validation
} catch (error) {
// 1. Identify all generic error messages in your codebase
// that use terms like "Oops", "Something went wrong",
// or "An error occurred"
// 2. Replace generic messages
// with specific descriptions of what happened
// 3. Add actionable guidance telling users
// exactly what they can do to resolve the issue
// 4. Implement proper internal logging
// to capture technical details for developers
logger.error('Payment validation failed', {
userId: paymentData.userId,
error: error.message,
stack: error.stack,
timestamp: new Date().toISOString()
});
// 5. Add monitoring alerts to notify
// the development team when errors occur frequently
alerting.notifyError('PAYMENT_VALIDATION_FAILED', error);
if (error.code === 'INVALID_CARD') {
return {
success: false,
userMessage: "Your card information" +
" appears to be incorrect." +
"Please check your card number," +
" expiry date, and security code."
};
}
return {
success: false,
userMessage: "There was a problem validating" +
" your payment." +
"Please try again or contact support."
};
}
// You should break this long method
// Using extract method
try {
chargeCard(paymentData);
} catch (error) {
logger.error('Card charging failed', {
userId: paymentData.userId,
error: error.message,
stack: error.stack,
timestamp: new Date().toISOString()
});
alerting.notifyError('CARD_CHARGING_FAILED', error);
if (error.code === 'INSUFFICIENT_FUNDS') {
return {
success: false,
userMessage: "Your payment couldn't be processed"+
" due to insufficient funds. " +
"Please use a different payment method" +
" or contact your bank."
};
}
if (error.code === 'CARD_EXPIRED') {
return {
success: false,
userMessage: "Your card has expired. " +
"Please update your payment method with a current card."
};
}
return {
success: false,
userMessage: "There was a problem processing your payment." +
" Please try again or contact support."
};
}
try {
sendConfirmation(paymentData.email);
} catch (error) {
logger.error('Confirmation sending failed', {
userId: paymentData.userId,
error: error.message,
stack: error.stack,
timestamp: new Date().toISOString()
});
alerting.notifyError('CONFIRMATION_FAILED', error);
return {
success: true,
userMessage: "Payment processed successfully,"+
" but we couldn't send the confirmation email." +
" Please check your email address or contact support."
};
}
return { success: true,
userMessage: "Payment processed successfully." };
}
Тип 📝
- [x]Руководство
Безопасность 🛡
Этот рефакторинг изменяет поведение и является безопасным, если вы продолжаете регистрировать и предупреждать активные для отладки.
Избегайте удаления деталей, необходимых командами поддержки.
Риск нарушения изменений низкий, так как вы улучшаете существующую обработку ошибок, а не изменяете основную бизнес -логику.
Почему код лучше? ✨
Вы даете пользователям полезное руководство вместо путаницы.
Вы создаете лучший пользовательский опыт, предоставляя четкую, действенную обратную связь вместо того, чтобы путать технический жаргон.
Пользователи понимают, что пошло не так, и знают их следующие шаги.
Вы разделяете проблемы, сохраняя технические данные в журналах, показывая пользователям, благоприятные для бизнеса.
Ваша команда поддержки получает лучшую информацию от отладки с помощью структурированного ведения журнала.
Вы можете активно решать проблемы системы путем мониторинга оповещений, прежде чем пользователи сообщают о них.
Вы держите техническую информацию вдали от них, но все еще записываете ее для более быстрого решения проблем.
Как это улучшает биение? 🗺
Вы поддерживаете ближе между реальным миром и своей моделью. Вместо расплывчатых сообщений «упс» ваша система говорит в четких терминах, которые отражают фактические события.
Сообщения об ошибках вРеальный мирсодержать конкретную информацию о том, что пошло не так и как ее исправить.
Кассир не говорит «упс, что -то пошло не так», когда ваша карта отклонена - они рассказывают вам конкретную проблему и предлагают решения.
Этот рефакторинг выравнивает программную модель сБиениеОшибки ошибок, делая систему более интуитивно понятной и полезной для пользователей
Ограничения ⚠
Вы должны быть осторожны, чтобы не раскрывать конфиденциальную системную информацию, которая может помочь нападающим.
Некоторые ошибки могут оставаться общими по соображениям безопасности (например, сбои аутентификации).
Кроме того, создание конкретных сообщений об ошибках требует большего времени разработки и тщательного тестирования сценариев ошибок.
Рефактор с ИИ 🤖
Предлагаемое подсказка: 1. Определите все общие сообщения об ошибках в вашей кодовой базе, которые используют такие термины, как «упс», «что -то пошло не так», или «произошла ошибка». 2. Замените общие сообщения на конкретные описания того, что произошло.
Без надлежащих инструкций | С конкретными инструкциями |
|---|---|
Чатгпт | Чатгпт |
Клод | Клод |
Недоумение | Недоумение |
Второй пилот | Второй пилот |
Ты | Ты |
Близнецы | Близнецы |
DeepSeek | DeepSeek |
Meta ai | Meta ai |
Грок | Грок |
Qwen | Qwen |
Теги 🏷
- Исключения
Уровень 🔋
- [x]Средний
Связанные рефакторные 🔄
https://hackernoon.com/refactoring-014-how-to-remove-if?embedable=true
Смотрите также 📚
https://hackernoon.com/fail-fast-philosophy-explained-si963vk9?embedable=true
https://www.morling.dev/blog/whats-in-a-good-error-message/?embedable=true
https://ulrikapark.wordpress.com/2021/05/03/are-you-sure-people-get-happy-about-your-oops-error-messages-or-does-it-their-trust-in-yourware/?embedable=true
https://www.sonarsource.com/learn/error-handling-guide/?embedable=true
Кредиты 🙏
Изображение поРайан МакгуайрнаPixabay
Эта статья является частью серии Refactoring.
https://maximilianocontieri.com/how-to-improve-your-code-with-easy-refactorings?embedable=true
Оригинал