Exceptions
For the Python SDK, we have organized our files within src/ such that each part is a directory, so it is clean and intuitive, then we create custom errors when needed. For example, all the custom errors that have to do with the API client object, is located within src/cript/api/exception.py and all exceptions for nodes are located within src/cript/nodes/exceptions.py. If we needed exceptions particular to only primary_nodes then we'd put them in src/cript/nodes/primary_nodes/exceptions.py
It is recommended to only have docstrings in the class definition and avoid docstrings for any other methods, the reason for this is because having docstrings for the exception methods will appear on the documentation and look unpleasant and be harder for the user to understand.
class APIError(CRIPTException):
"""
## Definition
This is a generic error made to display API errors to the user to troubleshoot.
## How to Fix
Please keep in mind that the CRIPT Python SDK turns the [Project](../../nodes/primary_nodes/project)
node into a giant JSON and sends that to the API to be processed. If there are any errors while processing
the giant JSON generated by the CRIPT Python SDK, then the API will return an error about the http request
and the JSON sent to it. Therefore, the error shown might be an error within the JSON and not particular
within the Python code that was created
The best way to trouble shoot this is to figure out what the API error means and figure out where
in the Python SDK this error occurred and what have been the reason under the hood.
"""
Custom exceptions can be helpful when the built-in exceptions provided by Python are too broad or do not convey the specific nature of the error. By defining custom exceptions, we can provide more granular information to users about the error and what happened.
Some errors either common sense and are easy to fix, however, custom exceptions usually are not as obvious or well known, so every custom exception should have a clean error message that states what went wrong and possibly how to fix it, keep in mind error messages should not be too long.
Ideally the exception should be raised in the right place within the code so that when the user is reading through the stack trace to figure out how and where the error occurred it makes it easy to understand. It would be hard to understand how to debug a program if an error occurred on line 5 of the code, but the error is pointing to line 20.
Error messages play a critical role in providing feedback to users when something goes wrong in a software application. Well-crafted error messages can greatly enhance the user experience by effectively communicating the issue and guiding users towards a resolution. This wiki page outlines some best practices for creating clear, concise, and user-friendly error messages.
It is also very important for the custom exception to have a detailed documentation on it. When the user gets confused from the exception, they should be able to bring up the documentation, read all about it, and then know exactly what happened, why it happened, and what steps they should take to debug it. Having a Troubleshoot section within each custom exception documentation can be very helpful as well.
Error messages should clearly and concisely convey what went wrong. Avoid using vague or ambiguous language that could confuse users. Provide specific information about the error, including any relevant error codes or identifiers, to assist users in understanding the problem.
Avoid using technical jargon or complex language in error messages. Instead, strive for simplicity and clarity. Use plain language that is easily understood by users who may not have technical expertise. This helps to minimize frustration and empowers users to take appropriate actions.
An effective error message should not only inform users about the problem but also provide actionable guidance on how to resolve it. Whenever possible, suggest steps or provide links to relevant documentation or resources that can assist users in troubleshooting or finding a solution.
Error messages should not blame or shame the user for the error. Instead, adopt a supportive and empathetic tone that acknowledges the problem and provides assistance. Make it clear that the error is a result of a system issue or a mistake that can be rectified.
Consider using visual cues, such as icons or color codes, to help differentiate between different types of errors. For example, you can use a warning icon for non-critical errors and an error icon for critical errors. Visual cues can quickly convey the severity of the issue and catch the user's attention.
Always test your error messages with real users to ensure they are effective and understandable. Collect feedback and iterate on your error messages based on user input. Continuously improving your error messages will enhance the overall user experience and reduce user frustration.
Remember, error messages should be treated as an opportunity to communicate with users and guide them through any problems they encounter. By following these best practices, you can create error messages that improve the user experience and promote user satisfaction.