From 56b0f034404b16c6b995dcd92503019bdc9da70e Mon Sep 17 00:00:00 2001 From: Donghyun Kim Date: Sat, 26 Oct 2024 17:58:46 +0900 Subject: [PATCH 1/8] Write code snippets related to error handling --- documentation/docs/error-handling.md | 18 ++++++++++++++++++ 1 file changed, 18 insertions(+) diff --git a/documentation/docs/error-handling.md b/documentation/docs/error-handling.md index 1cd58462..e61bdc21 100644 --- a/documentation/docs/error-handling.md +++ b/documentation/docs/error-handling.md @@ -12,6 +12,24 @@ There are recommended practices for managing errors in real-world applications. We recommend that you _not_ write panicking code at all, since Rust has the idiomatic `Result`. Additionally, Rust _cannot_ catch panics on the web platform (`wasm32-unknown-unknown`), which can cause callers to wait indefinitely. +```rust title="Rust" +fn not_good() { + let option = get_option(); + let value_a = option.unwrap(); + let result = get_result(); + let value_b = result.expect("This code can panic"); +} + +fn good() -> Result<(), SomeError> { + let option = get_option(); + let value_a = option?; + let result = get_result(); + let value_b = result?; +} +``` + +As the Rust documentation states, [most errors aren't serious enough](https://doc.rust-lang.org/book/ch09-02-recoverable-errors-with-result.html) to require the program or task to stop entirely. + ## ๐ŸŒˆ Flexible Error Type To manage Rust errors effectively, using a flexible error type is beneficial. From 37b457b30d93bb0ae7b4827b8032bc1bcc063f85 Mon Sep 17 00:00:00 2001 From: Donghyun Kim Date: Sat, 26 Oct 2024 18:05:12 +0900 Subject: [PATCH 2/8] Improve sentences in flexible error type --- documentation/docs/error-handling.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/documentation/docs/error-handling.md b/documentation/docs/error-handling.md index e61bdc21..96bc56af 100644 --- a/documentation/docs/error-handling.md +++ b/documentation/docs/error-handling.md @@ -34,9 +34,9 @@ As the Rust documentation states, [most errors aren't serious enough](https://do To manage Rust errors effectively, using a flexible error type is beneficial. -Developing an app differs from creating a library, as an app may encounter a wide range of error situations. Declaring distinct error types for hundreds of potential failures can be overwhelming. Therefore, it is advisable to utilize a single, flexible error type. +Developing an app differs from creating a library, as an app may encounter a wide range of error situations. Declaring a distinct error type for each potential failure can be overwhelming, unless the error cases are simple enough. -You can define your own custom error type or simply use one from `crates.io`: +Therefore, it is advisable to utilize a single, flexible error type. You can define your own or simply use one from `crates.io`: - [anyhow](https://crates.io/crates/anyhow) @@ -44,6 +44,8 @@ You can define your own custom error type or simply use one from `crates.io`: use anyhow::Result; fn get_cluster_info() -> Result { + // `anyhow::Error` can be created from any error type. + // By using the `?` operator, the conversion happens automatically. let config = std::fs::read_to_string("cluster.json")?; let map: ClusterMap = serde_json::from_str(&config)?; Ok(map) From a3cf363a0cc156f8d7841fac3cbfd7ea36d3979c Mon Sep 17 00:00:00 2001 From: Donghyun Kim Date: Sat, 26 Oct 2024 18:06:10 +0900 Subject: [PATCH 3/8] Add a comment --- documentation/docs/error-handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/error-handling.md b/documentation/docs/error-handling.md index 96bc56af..dcd8ee44 100644 --- a/documentation/docs/error-handling.md +++ b/documentation/docs/error-handling.md @@ -15,7 +15,7 @@ We recommend that you _not_ write panicking code at all, since Rust has the idio ```rust title="Rust" fn not_good() { let option = get_option(); - let value_a = option.unwrap(); + let value_a = option.unwrap(); // This code can panic let result = get_result(); let value_b = result.expect("This code can panic"); } From 366eb1f8fd9f75ed99c3eb74769763d6a9930c2d Mon Sep 17 00:00:00 2001 From: Donghyun Kim Date: Sat, 26 Oct 2024 18:06:40 +0900 Subject: [PATCH 4/8] Replace a word --- documentation/docs/error-handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/error-handling.md b/documentation/docs/error-handling.md index dcd8ee44..3ed758eb 100644 --- a/documentation/docs/error-handling.md +++ b/documentation/docs/error-handling.md @@ -10,7 +10,7 @@ There are recommended practices for managing errors in real-world applications. ## ๐ŸŒช๏ธ No Panicking -We recommend that you _not_ write panicking code at all, since Rust has the idiomatic `Result`. Additionally, Rust _cannot_ catch panics on the web platform (`wasm32-unknown-unknown`), which can cause callers to wait indefinitely. +We recommend that you _not_ write panicking code at all, since Rust has the idiomatic `Result`. Additionally, Rust _cannot_ catch panics on the web platform (`wasm32-unknown-unknown`), which can cause callers to wait forever. ```rust title="Rust" fn not_good() { From f623ed8ba562ee4b2c00579d715c5d333a0ee9e0 Mon Sep 17 00:00:00 2001 From: Donghyun Kim Date: Sat, 26 Oct 2024 18:07:48 +0900 Subject: [PATCH 5/8] Clarify a sentence --- documentation/docs/error-handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/error-handling.md b/documentation/docs/error-handling.md index 3ed758eb..5e7e1b09 100644 --- a/documentation/docs/error-handling.md +++ b/documentation/docs/error-handling.md @@ -109,7 +109,7 @@ async fn main_task() { } ``` -This is how to use a top-level async function to report the propagated error. You will almost always use the `.report()` method because Rust automatically warns you about unused `Result`s. +This is how to use a top-level function to report the propagated error. You will almost always use the `.report()` method because Rust automatically warns you about unused `Result`s. ## ๐Ÿงพ Logging From 28134f37c498adf7046a2343204f27fe38f87bc9 Mon Sep 17 00:00:00 2001 From: Donghyun Kim Date: Sat, 26 Oct 2024 18:11:29 +0900 Subject: [PATCH 6/8] Rename a function in snippets --- documentation/docs/error-handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/error-handling.md b/documentation/docs/error-handling.md index 5e7e1b09..af97cb13 100644 --- a/documentation/docs/error-handling.md +++ b/documentation/docs/error-handling.md @@ -103,7 +103,7 @@ async fn do_work() -> Result<()> { Ok(()) } -async fn main_task() { +async fn top_level() { let result = do_work().await; result.report(); } From f74a2e20d8c8baa0ac787e64f85d43d517b046d3 Mon Sep 17 00:00:00 2001 From: Donghyun Kim Date: Sat, 26 Oct 2024 18:11:50 +0900 Subject: [PATCH 7/8] Rename functions in snippets --- documentation/docs/error-handling.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/documentation/docs/error-handling.md b/documentation/docs/error-handling.md index af97cb13..d307b6b4 100644 --- a/documentation/docs/error-handling.md +++ b/documentation/docs/error-handling.md @@ -96,14 +96,14 @@ async fn make_http_request() -> Result { // It can be any kind of failable function. } -async fn do_work() -> Result<()> { +async fn top_level() -> Result<()> { let my_response = make_http_request().await?; // Do something with `my_response`. // Additional processing may be written here. Ok(()) } -async fn top_level() { +async fn main_task() { let result = do_work().await; result.report(); } From a413e84587a84d302582f3d628d820f3fec6563e Mon Sep 17 00:00:00 2001 From: Donghyun Kim Date: Sat, 26 Oct 2024 18:11:58 +0900 Subject: [PATCH 8/8] Fix the code snippet --- documentation/docs/error-handling.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/documentation/docs/error-handling.md b/documentation/docs/error-handling.md index d307b6b4..82945539 100644 --- a/documentation/docs/error-handling.md +++ b/documentation/docs/error-handling.md @@ -104,7 +104,7 @@ async fn top_level() -> Result<()> { } async fn main_task() { - let result = do_work().await; + let result = top_level().await; result.report(); } ```