From 7fd4f8bb2fdac9b6ebb048fccf8d34da9bd83a10 Mon Sep 17 00:00:00 2001
From: Rob Pike <r@golang.org>
Date: Mon, 27 Oct 2014 17:08:50 -0700
Subject: 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://codereview.appspot.com/158500043
---
 doc/go_mem.html | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

(limited to 'doc')

diff --git a/doc/go_mem.html b/doc/go_mem.html
index 2ea1ded7a..5dd48ff7f 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>
-- 
cgit v1.2.1