Summarizing the points and best practices that I have learned while writing Meshkit errors:
- Be clear and specific so that it is useful for end-users.
- Try to have the perspective of the end-users on what they will see and interpret.
- Avoid technical jargon unless necessary for understanding.
- Ensure the description is free of grammatical errors and properly punctuated.
- List all plausible causes, from most to least likely.
- Include both user input errors and potential system issues.
- Consider different scenarios and suggest multiple approaches when applicable.
For short description:- Provide a summary of the error in a single sentence.
- Example:
Unable to convert base64 to UTF8.
Long Description:- It is recommended to always use err.Error() in the long description, which makes it straightforward for many cases.
- Provide context about when and why the error might occur when defining.
- Example:
This error occurs when an attempt is made to decode an invalid base64 string or one that doesn't represent UTF-8 encoded text.
Probable Causes:- Identify the potential reasons for the error.
- Example:
Non-UTF-8 Data: The decoded base64 data might not represent valid UTF-8 encoded text. It could be binary data, a different character encoding, or simply corrupted.
Suggested Remediation:- Provide actionable steps to resolve the error.
- Example:
Validate Input: Ensure the input string contains only valid base64 characters and correct padding.", "Check Encoding: Verify the decoded data is UTF-8
