[karmakaze]

What I've come to learn from using Go on a number of projects and reading the long mailing list threads on topics that lead to the decisions and development of language features is that Go is a language intended for many programmers (e.g. average) to be successful writing systems(-like) software. Officially, it was meant to be for systems software, but it's since expanded beyond that scope. Given that it's designed and developed by very bright authors for everyday programmers, it's actually surprising how much thought has gone into seemingly obvious language features. They want users of the language to be successful more than they want their users ego to be happy about language features.

Given that, they do also 'talk down' in their official documentation. I had to look back in time to understand the memory model for the sync.atomic operations which is documented:

"These functions require great care to be used correctly. Except for special, low-level applications, synchronization is better done with channels or the facilities of the sync package. Share memory by communicating; don't communicate by sharing memory."

The final word on what 'great care' means is that Go doesn't actually have a memory model for this part of the standard library. The discussion thread around it has a different tone than the official documentation. They agree on how they want implementations to operate, but don't feel that it needs to be officially defined or documented. I would have been happy if they at least referenced the discussion thread rather than merely label it 'great care' meaning 'not for you'. The other thing you find is that the performant parts of the standard library often does not follow "Share memory by communicating; don't communicate by sharing memory".

One of the betrayals when working with I/O was finding that standard library routines can return a value AND an error, and that sometimes a non-nil error is not an error (EOF is not the only one of these).