From 64b100232efe7cb10388b6dc586007e02a74d5a3 Mon Sep 17 00:00:00 2001
From: Alejandro Santiago <me@alestiago.com>
Date: Tue, 3 Sep 2024 12:49:32 +0100
Subject: [PATCH] docs: add error handling practices

---
 .../docs/error_handling/error_handling.md     | 105 ++++++++++++++++++
 1 file changed, 105 insertions(+)
 create mode 100644 src/content/docs/error_handling/error_handling.md

diff --git a/src/content/docs/error_handling/error_handling.md b/src/content/docs/error_handling/error_handling.md
new file mode 100644
index 0000000..40589be
--- /dev/null
+++ b/src/content/docs/error_handling/error_handling.md
@@ -0,0 +1,105 @@
+---
+title: Error handling
+description: Error handling best practices.
+---
+
+## Document when a call may throw
+
+Inform about the potential risks associated with calling a function, helping understand under what conditions an exception might be thrown.
+
+This transparency allows developers to handle exceptions properly, leading to more robust and error-resistant code. Thus, reducing the likelihood of unintended errors.
+
+<Tabs>
+  <TabItem label="Good ✅">
+
+```dart
+/// Deletes permanenetly an account with the given [name].
+///
+/// Throws:
+///
+/// * [UnothorizedException] if the active role is not [Role.admin], since only
+///  admins are authorized to delete accounts.
+void deleteAccount(String name) {
+  if (activeRole != Role.admin) {
+    throw UnothorizedException('Only admin can delete account');
+  }
+  // ...
+}
+```
+
+  </TabItem>
+  <TabItem label="Bad ❗️">
+
+```dart
+/// Deletes permanenetly an account with the given [name].
+void deleteAccount(String name) {
+  if (activeRole != Role.admin) {
+    throw UnothorizedException('Only admin can delete account');
+  }
+  // ...
+}
+```
+
+  </TabItem>
+</Tabs>
+
+## Define implemented exceptions
+
+Implement `Exception` with descriptive names rather than simply throwing a generic `Exception`.
+
+By creating custom exceptions, developers can provide more meaningful error messages and handle different error types in a more granular way. This enhances code readability and maintainability, as it becomes clear what type of error is being dealt with.
+
+<Tabs>
+  <TabItem label="Good ✅">
+
+```dart
+class UnothorizedException implements Exception {
+  UnothorizedException(this.message);
+
+  final String message;
+
+  @override
+  String toString() => 'UnothorizedException: $message';
+}
+
+void deleteAccount(String name) {
+  if (activeRole != Role.admin) {
+    throw UnothorizedException('Only admin can delete account');
+  }
+  // ...
+}
+
+void main() {
+  try {
+    deleteAccount('user');
+  } on UnothorizedException catch (e) {
+    // Handle the exception.
+  }
+}
+
+```
+
+  </TabItem>
+  <TabItem label="Bad ❗️">
+
+```dart
+void deleteAccount(String name) {
+  if (activeRole != Role.admin) {
+    throw Exception('Only admin can delete account');
+  }
+  // ...
+}
+
+void main() {
+  try {
+    deleteAccount('user');
+  } on Exception catch (e) {
+    // Exception is a marker interface implemented by all core library exceptions,
+    // it is very generic and it could be catching many different types of exceptions,
+    // lacking intent and making the code harder to understand.
+  }
+}
+```
+
+  </TabItem>
+</Tabs>