From: Rob Pike <r@golang.org>
Date: Tue, 28 Oct 2014 00:08:50 +0000 (-0700)
Subject: doc/go_mem.html: don't be clever
X-Git-Tag: go1.4beta1~36
X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=2eb1b658305bfd32774fd1e6a32cd6463564cf89;p=gostls13.git

doc/go_mem.html: don't be clever

Add a short introductory section saying what most Go
programmers really need to know, which is that you
shouldn't have to read this document to understand
the behavior of your program.

LGTM=bradfitz, adg, tracey.brendan, iant, rsc, dsymonds
R=golang-codereviews, bradfitz, tracey.brendan, adg, iant, rsc, dsymonds
CC=golang-codereviews
https://golang.org/cl/158500043
---

diff --git a/doc/go_mem.html b/doc/go_mem.html
index 2ea1ded7a3..5dd48ff7fb 100644
--- a/doc/go_mem.html
+++ b/doc/go_mem.html
@@ -21,6 +21,29 @@ reads of a variable in one goroutine can be guaranteed to
 observe values produced by writes to the same variable in a different goroutine.
 </p>
 
+
+<h2>Advice</h2>
+
+<p>
+Programs that modify data being simultaneously accessed by multiple goroutines
+must serialize such access.
+</p>
+
+<p>
+To serialize access, protect the data with channel operations or other synchronization primitives
+such as those in the <a href="/pkg/sync/"><code>sync</code></a>
+and <a href="/pkg/sync/atomic/"><code>sync/atomic</code></a> packages.
+</p>
+
+<p>
+If you must read the rest of this document to understand the behavior of your program,
+you are being too clever.
+</p>
+
+<p>
+Don't be clever.
+</p>
+
 <h2>Happens Before</h2>
 
 <p>