From fb5abc7fbf0aae6a13a9f709f61d964ed8d044cb Mon Sep 17 00:00:00 2001 From: Camelid Date: Mon, 23 Nov 2020 14:21:13 -0800 Subject: [PATCH 1/2] Document when errors should have an associated error code --- src/diagnostics.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/src/diagnostics.md b/src/diagnostics.md index 04745ee98..9c545503d 100644 --- a/src/diagnostics.md +++ b/src/diagnostics.md @@ -70,10 +70,14 @@ example of how to trigger it and advice on how to fix it. Please read [RFC 1567] for details on how to format and write long error codes. -The descriptions are written in markdown, and all of them are linked in the +The descriptions are written in Markdown, and all of them are linked in the [`rustc_error_codes`] crate. -TODO: When should an error use an error code, and when shouldn't it? +As a general rule, errors should have an associated error code if the problem is +complicated enough or frequent enough that it would be helpful to have a +long-form explanation. For example, borrow-check and type-check errors tend to +have error codes, but many parse errors do not. If you are not sure, just ask +your reviewer! [`rustc_error_codes`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_error_codes/error_codes/index.html [error index]: https://doc.rust-lang.org/error-index.html From 61b4386166d9e0496fa3d15ba07e5246e3e5321c Mon Sep 17 00:00:00 2001 From: Camelid Date: Tue, 24 Nov 2020 15:24:18 -0800 Subject: [PATCH 2/2] Update general rule --- src/diagnostics.md | 15 ++++++++++----- 1 file changed, 10 insertions(+), 5 deletions(-) diff --git a/src/diagnostics.md b/src/diagnostics.md index 9c545503d..fe75c2215 100644 --- a/src/diagnostics.md +++ b/src/diagnostics.md @@ -73,15 +73,20 @@ codes. The descriptions are written in Markdown, and all of them are linked in the [`rustc_error_codes`] crate. -As a general rule, errors should have an associated error code if the problem is -complicated enough or frequent enough that it would be helpful to have a -long-form explanation. For example, borrow-check and type-check errors tend to -have error codes, but many parse errors do not. If you are not sure, just ask -your reviewer! +As a general rule, give an error a code (with an associated explanation) if the +explanation would give more information than the error itself. A lot of the time +it's better to put all the information in the emitted error itself. However, +sometimes that would make the error verbose or there are too many possible +triggers to include useful information for all cases in the error, in which case +it's a good idea to add an explanation.[^estebank] +As always, if you are not sure, just ask your reviewer! + +[^estebank]: This rule of thumb was suggested by **@estebank** [here][estebank-comment]. [`rustc_error_codes`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_error_codes/error_codes/index.html [error index]: https://doc.rust-lang.org/error-index.html [RFC 1567]: https://github.com/rust-lang/rfcs/blob/master/text/1567-long-error-codes-explanation-normalization.md +[estebank-comment]: https://github.com/rust-lang/rustc-dev-guide/pull/967#issuecomment-733218283 ### Lints versus fixed diagnostics