go/analysis/passes/fieldalignment: document "false sharing"

...and don't claim that the most compact field order is optimal.
The exception is relatively obscure, but the fact that it exists
is important because it means it is not safe to apply the code
transformation unconditionally.

Change-Id: I391fbc1872b578d5340dd7c8fded48be30b820e0
Reviewed-on: https://go-review.googlesource.com/c/tools/+/415057
Reviewed-by: Robert Findley <[email protected]>

Author: adonovan

go/analysis/passes/fieldalignment/fieldalignment.go

@@ -23,7 +23,7 @@ import (
 const Doc = `find structs that would use less memory if their fields were sorted
 
 This analyzer find structs that can be rearranged to use less memory, and provides
-a suggested edit with the optimal order.
+a suggested edit with the most compact order.
 
 Note that there are two different diagnostics reported. One checks struct size,
 and the other reports "pointer bytes" used. Pointer bytes is how many bytes of the
@@ -41,6 +41,11 @@ has 24 pointer bytes because it has to scan further through the *uint32.
 	struct { string; uint32 }
 
 has 8 because it can stop immediately after the string pointer.
+
+Be aware that the most compact order is not always the most efficient.
+In rare cases it may cause two variables each updated by its own goroutine
+to occupy the same CPU cache line, inducing a form of memory contention
+known as "false sharing" that slows down both goroutines.
 `
 
 var Analyzer = &analysis.Analyzer{