Azure / Azure/typespec-azure

Design and implement an effective error message sub-system for our code generation tool

Open
#2,070 2 comments 0 reactions 1 assignee Claimed by @ArcturusZhang View on GitHub
epic feature
Dominant language
TypeScript
Stars
27
Forks
90
Avg merge
1d 22h
Merged PRs (30d)
156

Description

We are moving fast, but our tools lack well-designed error messages. Unlike any formal compiler, which provides clear error codes and messages to help developers identify and resolve issues efficiently, we only throw exceptions with lengthy call stack information, which is very user-unfriendly.
Designing an effective error message sub-system is crucial for enhancing user experience and minimizing frustration.
The error message from our tool should be:
1. **Clear and Unambiguous Messages**: Ensure that error messages are simple, easy to understand, and contextually relevant. Avoid technical jargon that might confuse users.
2. **Strategic Placement**: Position error messages near the relevant field to make it easier for users to identify and correct the issue.
3. **Provide Solutions**: Good error messages not only highlight the problem but also offer solutions.
4. **Avoid Blaming the User**: Frame error messages in a way that doesn't place blame on the user. For example, instead of saying "You did not specify the format of the property XXX," use "Please specify the form of the property XXX".

```[tasklist]
### Features
- [ ] https://github.com/microsoft/typespec/issues/3347
- [ ] https://github.com/microsoft/typespec/issues/5575
- [ ] https://github.com/microsoft/typespec/issues/5576
- [ ] https://github.com/microsoft/typespec/issues/5578
- [ ] https://github.com/Azure/autorest.go/issues/1485
- [ ] https://github.com/Azure/autorest.typescript/issues/2991
- [ ] https://github.com/Azure/autorest.csharp/issues/5176
```

```[tasklist]
### Related tasks
- [ ] https://github.com/Azure/autorest.csharp/issues/2913
- [ ] https://github.com/Azure/autorest.csharp/issues/5190
- [ ] https://github.com/Azure/autorest.csharp/issues/5192
- [ ] https://github.com/Azure/azure-sdk-for-net/issues/37826
- [ ] https://github.com/Azure/autorest.csharp/issues/4691
- [ ] https://github.com/Azure/autorest.csharp/issues/5176
- [ ] https://github.com/microsoft/typespec/issues/5508
- [ ] https://github.com/microsoft/typespec/issues/5509
- [ ] https://github.com/microsoft/typespec/issues/5511
- [ ] https://github.com/Azure/autorest.typescript/issues/2979
- [ ] https://github.com/Azure/autorest.go/issues/1484
- [ ] https://github.com/microsoft/typespec/issues/5660
```

Contributor guide

Open the contributing guide

Assessment

This issue has not been assessed yet.

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.