affected/package: documentation

[mneverov]

Please remove Don't be clever advice from the memory model.

The statement is annoying. I think there is no other language that has such advice in their specification.
Does this advice apply to go core team too?

[mneverov]

@rsc let's plan it, reopen the issue and fix the docs

[ianlancetaylor]

We stand by the statement. Go is an opinionated language and that is our opinion.

[mneverov]

@ianlancetaylor,
sorry, but i still don't get why you discourage everyone from reading the documentation.
If the advice denotes a part of the language that not every developer should know then let's be consistent and add the advice to every part of the spec. beyond syntax explanation. Surely, GC is one of these "advanced" topics but there is no advice there.

Let me try to explain how I read the advice:

We, the best developers in the world, already took care about go memory model, so you, not so smart developer, can implement your stupid tiny web services without understanding how it works.

Currently, every web service uses prometheus for metrics, which atomics. Unfortunately, there is indeed no reason to read the specification since there is nothing about atomics.

Is it possible to change the sentence from "don't be clever" to "act on your own risk" or something like that?

[ianlancetaylor]

We may disagree on what the memory model document says. When I look at it, the memory model does not tell people not to read the documentation. It tells people to not write programs to rely on the details of the memory model. We're not discouraging people from reading and understanding it.

Thanks for pointing out that #5045 was still open. It was fixed back in January and when the 1.19 release comes out, fairly soon, that fix will be visible on at https://go.dev/ref/mem. I closed #5045.