Attempting the connection with a firewall blocking the necessary ports<\/li>\n<\/ul>\nComprehensive Error Documentation and Guidance<\/h2>\n
Once we’ve triggered and documented these errors, we can create informative error messages and guidance. Let’s look at a real-world example of how this might be implemented:<\/p>\n
def connect(self, ip, waiting=True):\r\n # ... (connection attempt code) ...\r\n\r\n while not self.is_connected and waiting:\r\n sleep(0.1)\r\n i = i + 1\r\n if i > 50:\r\n print(\"\")\r\n width = len(\"Make sure your laptop is not using a firewall or other security software that blocks the connection\") + 3\r\n print(\"\")\r\n print(\" Could not connect to robot, please check the following:\")\r\n print(\" - Make sure the robot is turned on\")\r\n print(\" - Make sure the laptop is connected to the same network as the robot\")\r\n print(\" - Make sure you have the correct ip address of the robot (\" + ip + \")\")\r\n print(\" - Make sure that your laptop is not using a firewall or other security software that blocks the connection\")\r\n hostname = socket.gethostname()\r\n IPAddr = socket.gethostbyname(hostname)\r\n print(\" - Your Computer Name is: \" + hostname)\r\n print(\" - Your Computer IP Address is: \" + IPAddr)\r\n print(f\"\\\\{'_' * width}\/\" + self.character)\r\n exit(1)<\/code><\/pre>\nIn this case it’s easy to catch the errors, as all the errors end up as a “Not being able to connect” error. So catching the error and then showing a useful error message with tips on what could have gone wrong can lead to a smoother experience for inexperienced users.<\/p>\n
When this code runs and runs into a timeout while trying to connect, it produces an output that looks like this:<\/p>\n
Trying to connect to ws:\/\/10.0.233.55\/live\r\nConnecting ..................................................\r\n\r\n Could not connect to robot, please check the following:\r\n - Make sure the robot is turned on\r\n - Make sure the laptop is connected to the same network as the robot\r\n - Make sure you have the correct ip address of the robot (10.0.233.55)\r\n - Make sure that your laptop is not using a firewall or other security software that blocks the connection\r\n - Your Computer Name is: user-laptop\r\n - Your Computer IP Address is: 192.168.1.100\r\n\\__________________________________________________________________________________________\/\r\n _-_ | \/\r\n\/_ \\ |\/\r\n(o)(o)\r\n| | |\r\n| \\\/ \/\r\n\\ |\r\n \u00af--\u00af<\/code><\/pre>\nThis error output demonstrates several key principles:<\/p>\n
\n- Clear Error Identification<\/strong>: It states that the connection to the robot failed.<\/li>\n
- Actionable Steps<\/strong>: It provides a list of specific things the user can check.<\/li>\n
- Relevant Context<\/strong>: It includes the IP address the user was trying to connect to (10.0.233.55).<\/li>\n
- Debug Information<\/strong>: It provides additional information like the user’s computer name and IP address.<\/li>\n
- Visual Separation<\/strong>: The error message is visually separated from other output, making it easy to read and understand.<\/li>\n
- Memorable Presentation<\/strong>: The inclusion of the ASCII art character adds a touch of personality and makes the error message stand out more. :)<\/li>\n<\/ol>\n
If there is a stacktrace, you should still display it, as it might contain more information about the error. In this case with the timeout there is no stacktrace from an exception.<\/p>\n
Implementing a Proactive Error Management Approach<\/h2>\n
To implement this approach in your own projects:<\/p>\n
\n- Map the Happy Path<\/strong>: Document the ideal flow through each feature or process.<\/li>\n
- Identify Deviation Points<\/strong>: For each step in the happy path, consider how users might deviate.<\/li>\n
- Trigger Errors Intentionally<\/strong>: Systematically cause each identified error scenario.<\/li>\n
- Document Thoroughly<\/strong>: For each triggered error, record:\n
\n- Steps to reproduce<\/li>\n
- Resulting error message or behavior<\/li>\n
- Relevant system state or environment details<\/li>\n<\/ul>\n<\/li>\n
- Craft Informative Error Messages<\/strong>: Based on your documentation, create error messages that:\n
\n- Clearly state what went wrong<\/li>\n
- Provide actionable steps for resolution<\/li>\n
- Include relevant context and debug information<\/li>\n<\/ul>\n<\/li>\n
- Implement in Code<\/strong>: Add these comprehensive error messages to your error handling logic.<\/li>\n
- Continuous Improvement<\/strong>: Regularly review and update your error catalog based on user feedback and new discoveries.<\/li>\n<\/ol>\n