Document when errors should have an associated error code

[camelid]

I don't know if there's an official guideline (that's why we need these docs!);
this is just what sounded reasonable to me.

r? @estebank

[jyn514]

Hmm, I don't know if this is a guideline so much as describing the current situation. I would say when in doubt, always add an error code (I've even made PRs adding error codes to errors that didn't have one before: rust-lang/rust#76143).

[camelid]

I don't know if there's an official guideline (that's why we need these docs!);
this is just what sounded reasonable to me.

^ @jyn514 That's what I was saying: this isn't some official guideline :)

[jyn514]

Right, yes, but I'm saying we shouldn't suggest it as a policy. This makes it seem like you shouldn't add error codes for parse errors, which I'm not sure is true.

[estebank]

@jyn514 parse errors in particular are tricky. I find that error codes work best when they are targeted and specific, meaning there is a small number of triggers for it and their description can give you enough context to fix the problem. There are some cases where the same error code has a bunch of solutions (E0277, E0308, for example), but for the most part that's fine. Parse errors in particular have a combination of things that we proactively handle (hey! missing semicolon here!) but the vast majority of them are kind of random and can be reached through multiple different kinds of unrelated mistakes. We could introduce a new generic error code for the general case of "E0666: parse error", and then take every case we proactively handle and give it its own error code. That would be fine, but I have instead focused on putting all the info that would be in the error code index into the error itself. When the index entry wouldn't have any more information, I don't bother creating a new code. Maybe that would be a good rule of thumb: give an error a code if the the index entry would give more info than the error itself which we haven't either because of verbosity or because we can't detect all the possible triggers.

@camelid I'm ok with the blurb you added, r=me if you don't want to expand it.

[jyn514]

Maybe that would be a good rule of thumb: give an error a code if the the index entry would give more info than the error itself which we haven't either because of verbosity or because we can't detect all the possible triggers.

Sounds great, thanks!

[camelid]

@estebank I changed the advice to something similar to what you suggested. Should be ready now!

[estebank]

@bors r+

Haha, wrong repo. 😅