bug#43557: 28.0.50; Please document which objects are mutable and which are not

[Stefan Monnier via "Bug reports for GNU Emacs, the Swiss army knife of text editors" <bug-gnu-emacs@gnu.org>]

>> but I'd say that using `setcar` above is risky because the user has
>> no guarantee about what it may impact.
> I think that a word like "risky" has no place in a reference manual.

It doesn't have its place in the part that describes technically the
effect of the operation.  It can have its place in the part that gives
recommendations for style and recommended practices.

> What does that even mean?  What are the risks?

That the effect goes further than the author anticipated.

> Why introduce such vague and confusing terminology to begin with?

In the hope of saving them (and/or others) some serious head scratching,
and more generally in the hope to improve the reliability of ELisp code
out there.

>> I think the rule is basically, that you should only ever use `setc[ad]r`
>> on cons cells you yourself created.
> What does "should" mean here?

It's here a recommendation and a request.

> What happens if users don't follow this "recommendation"?

Experience teaches us that when a piece of code uses `setcar` on
a cons-cell built by some "unrelated" piece of code, there's a high
probability that sooner or later the `setcar` will end up modifying more
data than intended (because that same cons cell is shared with some
other "unrelated" data structure).
I.e. you get a bug; one that can take a fair bit of effort to track down.

> How do they identify "cons cells you yourself created"?

When in doubt, assume that it's not "a cons cells you yourself created".

> Again, I think such terminology brings up more questions than it answers.

Agreed.  Mutation is pretty nasty, indeed.

>> But indeed the manual fails to document which functions guarantee to
>> return "fresh" new cells, which makes it hard to know which cells
>> "you yourself created".
> Then let's document that (while avoiding terms such as "you yourself created").

I'd welcome that, yes.

> Can we find a wording that we agree on and put it into the manual?

I can't think of a reason why not.


        Stefan