Add In-Band Errors.

CodeReviewComments.md

@@ -22,6 +22,7 @@ You can view this as a supplement to https://golang.org/doc/effective_go.html.
 * [Handle Errors](#handle-errors)
 * [Imports](#imports)
 * [Import Dot](#import-dot)
+* [In-Band Errors](#in-band-errors)
 * [Indent Error Flow](#indent-error-flow)
 * [Initialisms](#initialisms)
 * [Line Length](#line-length)
@@ -223,6 +224,58 @@ import (
 
 In this case, the test file cannot be in package foo because it uses bar/testutil, which imports foo.  So we use the 'import .' form to let the file pretend to be part of package foo even though it is not.  Except for this one case, do not use import . in your programs.  It makes the programs much harder to read because it is unclear whether a name like Quux is a top-level identifier in the current package or in an imported package.
 
+## In-Band Errors
+
+In C and similar languages, it's common for functions to return values like -1 
+or null to signal errors or missing results:
+
+```go
+// Lookup returns the value for key or "" if there is no mapping for key.
+func Lookup(key string) string
+
+// Failing to check a for an in-band error value can lead to bugs:
+Parse(Lookup(key))  // returns "parse failure for value" instead of "no value for key"
+```
+
+Go's support for multiple return values provides a better solution.
+Instead requiring clients to check for an in-band error value, a function should return
+an additional value to indicate whether its other return values are valid. This return
+value may be an error, or a boolean when no explanation is needed.
+It should be the final return value.
+
+``` go
+// Lookup returns the value for key or ok=false if there is no mapping for key.
+func Lookup(key string) (value string, ok bool)
+```
+
+This prevents the caller from using the result incorrectly:
+
+``` go
+Parse(Lookup(key))  // compile-time error
+```
+
+And encourages more robust and readable code:
+
+``` go
+value, ok := Lookup(key)
+if !ok  {
+    return fmt.Errorf("no value for %q", key)
+}
+return Parse(value)
+```
+
+This rule applies to exported functions but is also useful
+for unexported functions.
+
+Return values like nil, "", 0, and -1 are fine when they are
+valid results for a function, that is, when the caller need not
+handle them differently from other values.
+
+Some standard library functions, like those in package "strings",
+return in-band error values. This greatly simplifies string-manipulation
+code at the cost of requiring more diligence from the programmer.
+In general, Google Go code should return additional values for errors.
+
 ## Indent Error Flow
 
 Try to keep the normal code path at a minimal indentation, and indent the error handling, dealing with it first. This improves the readability of the code by permitting visually scanning the normal path quickly. For instance, don't write: