Policy: Documenting *why* something works in a particular way

[ehuss]

Should the spec ever mention why something works in a particular way?
In the Reference, we have generally avoided that, but I think that is a detriment to some readers, since just specifying the behavior of something can be extremely hard to understand why it matters, or how it is relevant to a Rust programmer.
That kind of information can provide useful and interesting context.

Graydon spoke highly of the Ada rationale (the 1979 version specifically), using it while working on Rust.

A very minor example: The type_length_limit attributes explains what it does, but not why it is there. I think it could be useful to have a note like: type_length_limit is used to prevent the compiler from hanging and to better deal with polymorphic recursion.

Regardless, I think it would be good to have a policy, as contributors sometimes include this information that we then need to tell them to remove. Guidelines could bring clarity on what we expect.

[mattheww]

I agree that pieces of rationale that come up naturally when describing a rule are likely to be helpful as informative notes.

They don't have to be explicitly phrased as rationale: in many cases, instead of saying "The rule is X because it allows Y"; the spec could say something like "Note: it follows from X that Y is allowed".

Looking at the bits in the Reference that are currently phrased as rationale, I think most of them would be worth keeping in some form, as informative notes.

For example:

This restriction exists because the register allocators in LLVM and GCC sometimes cannot handle tied operands with different types.

Although the :: token is allowed before the generics arguments, it is not
required because there is no ambiguity like there is in PathInExpression.

But perhaps the spec should avoid making claims about why the design is as it is that aren't tied in this sort of way to some direct consequence.

For example, tokens.md in the Reference currently has this to say about \x escapes in string literals:

Higher values are not permitted because it is ambiguous whether they mean Unicode code points or byte values.

But there's now an accepted RFC to permit them, picking one side of that ambiguity.

(The Ada rationale was written by the team of designers at the time when they were writing the design. Our circumstances are different, so I don't think we could aim for something similar even if the effort was available.)