From f0ccd40736f78474b3fcc41381d4e2054fa983c8 Mon Sep 17 00:00:00 2001 From: Rob Pike Date: Thu, 20 Aug 2009 15:39:41 -0700 Subject: [PATCH] names R=rsc DELTA=96 (25 added, 5 deleted, 66 changed) OCL=33607 CL=33612 --- doc/effective_go.html | 124 ++++++++++++++++++++++++------------------ 1 file changed, 72 insertions(+), 52 deletions(-) diff --git a/doc/effective_go.html b/doc/effective_go.html index ab900b266e..b7b948d8e5 100644 --- a/doc/effective_go.html +++ b/doc/effective_go.html @@ -250,86 +250,106 @@ var (

Names

-

Use MixedCaps

-

-Go uses the case of the first letter in a name to decide -whether the name is visible in other packages. -Multiword names use MixedCaps or mixedCaps -rather than underscores. +Names are as important in Go as in any other language. +In some cases they even have semantic effect: for instance, +the visibility of a name outside a package is determined by whether its +first character is an upper case letter, +while methods are looked up by name alone (although the type must match too). +It's therefore worth spending a little time talking about naming conventions +in Go programs.

-

Use short package names

+ +

Package names

-Package names are lower case single-word names: -there should be no need for underscore or mixedCaps. -The package name is conventionally the base name of -the source directory: the package in src/pkg/container/vector +When a package is imported, the package name becomes an accessor for the +contents. After +

+ +
+import "bytes"
+
+ +

+the importing package can talk about bytes.Buffer. It's +helpful if everyone using the package can use the same name to refer to +its contents, which implies that the package name should be good: +short, concise, evocative. By convention, packages are given +lower case, single-word names; there should be no need for underscores +or mixedCaps. +Err on the side of brevity, since everyone using your +package will be typing that name. +And don't worry about collisions a priori. +The package name is only the default name for imports; it need not be unique +across all source code, and in the rare case of a collision the +importing package can choose a different name to use locally. +

+ +

+Another convention is that the package name is the base name of +its source directory; +the package in src/pkg/container/vector is installed as "container/vector" but has name vector, not container_vector and not containerVector. -The package name is only the default name used -when importing the package; it need not be unique -across all source code. -

- -

Avoid long names

- -

-A name's length should not exceed its information content. -For a function-local variable -in scope only for a few lines, the name i conveys just -as much information as index or idx and is easier to read. -Letters are easier to distinguish than numbers; use i and j -not i1 and i2.

-Exported names must convey more information -because they appear far from their origin. -Even so, longer names are not always better, -and the package name can help convey information: -the buffered Reader is bufio.Reader, not bufio.BufReader. -Similarly, once.Do is as precise and evocative as -once.DoOrWaitUntilDone, and once.Do(f) reads -better than once.DoOrWaitUntilDone(f). -Encoding small essays into function names is not Go style; -using clear names supported by good documentation is. +The importer of a package will use the name to refer to its contents +(the import . notation is intended mostly for tests and other +unusual situations), and exported names in the package can use that fact +to avoid stutter. +For instance, the buffered reader type in the bufio package is called Reader, +not BufReader, because users see it as bufio.Reader, +which is a clear, concise name. +Moreover, +because imported entities are always addressed with their package name, bufio.Reader +does not conflict with io.Reader. +Use the package structure to help you choose good names.

-

Use the -er convention for interface names

+

+Another short example is once.Do; +once.Do(setup) reads well and would not be improved by +writing once.DoOrWaitUntilDone(setup). +Long names don't automatically make things more readable. +If the name represents something intricate or subtle, it's usually better +to write a helpful doc comment than to attempt to put all the information +into the name. +

+ +

Interface names

-One-method interfaces are conventionally named by +By convention, one-method interfaces are named by the method name plus the -er suffix: Reader, -Writer, Formatter. +Writer, Formatter etc.

-

Use canonical names

-

-XXX permits interfaces String() not ToString() XXX -A few method names—Read, Write, Close, Flush, String—have +There are a number of such names and it's productive to honor them and the function +names they capture. +Read, Write, Close, Flush, +String and so on have canonical signatures and meanings. To avoid confusion, don't give your method one of those names unless it has the same signature and meaning. Conversely, if your type implements a method with the same meaning as a method on a well-known type, -give it the same name and signature. +give it the same name and signature; +call your string-converter method String not ToString.

+

MixedCaps

+

-Some function-local variables have canonical names too. -Just as i is idiomatic in Go for an -index variable, n is idiomatic for a count, b for a []byte, -s for a string, r for a Reader, -err for an os.Error -and so on. -Don't mix shorthands: it is especially confusing to -have two different variables i and idx, -or n and cnt. +Finally, the convention in Go is to used MixedCaps +or mixedCaps rather than underscores to write +multiword names.

+

Idioms

Allocate using literals