-Programmers often want their style to be distinctive, -writing loops backwards or using custom spacing and -naming conventions. Such idiosyncracies come at a -price, however: by making the code look different, -they make it harder to understand. -Consistency trumps personal -expression in programming. -
- --If a program does the same thing twice, -it should do it the same way both times. -Conversely, if two different sections of a -program look different, the reader will -expect them to do different things. -
- -
-Consider for loops.
-Traditionally, a loop over n
-elements begins:
-
-for i := 0; i < n; i++ {
-
-
--Much of the time, the loop could run in the opposite order -and still be correct: -
- -
-for i := n-1; i >= 0; i-- {
-
-
--The convention -is to count up unless to do so would be incorrect. -A loop that counts down implicitly says “something -special is happening here.” -A reader who finds a program in which some -loops count up and the rest count down -will spend time trying to understand why. -
- -
-Loop direction is just one
-programming decision that must be made
-consistently; others include
-formatting, naming variables and methods,
-whether a type
-has a constructor, what tests look like, and so on.
-Why is this variable called n here and cnt there?
-Why is the Log constructor CreateLog when
-the List constructor is NewList?
-Why is this data structure initialized using
-a structure literal when that one
-is initialized using individual assignments?
-These questions distract from the important one:
-what does the code do?
-Moreover, internal consistency is important not only within a single file,
-but also within the the surrounding source files.
-When editing code, read the surrounding context
-and try to mimic it as much as possible, even if it
-disagrees with the rules here.
-It should not be possible to tell which lines
-you wrote or edited based on style alone.
-Consistency about little things
-lets readers concentrate on big ones.
-
n and cnt.
-Taking the address of a struct or array literal evaluates to a -new instance each time it is evaluated. -Use these expressions to avoid the repetition of filling +A struct literal is an expression that creates a +new instance each time it is evaluated. The address of such +an expression therefore points to a fresh instance each time. +Use such expressions to avoid the repetition of filling out a data structure.
+length := Point{x, y}.Abs();
+
// Prepare RPCMessage to send to server
rpc := &RPCMessage {
Version: 1,
@@ -427,6 +354,11 @@ rpc := &RPCMessage {
};
++Array, slice, and map literals behave similarly, although it is +unusual to need the address of a slice or map. +
+
@@ -586,17 +518,20 @@ type PathError struct {
}
func (e *PathError) String() string {
- return e.Op + " " + e.Path + ": " + e.Error.String();
+ return e.Op + " " + e.Path + ": " + e.Error.String();
}
+
PathError's String formats
the error nicely, including the operation and file name
tha failed; just printing the error generates a
message, such as
+
open /etc/passwx: no such file or directory+
that is useful even if printed far from the call that triggered it.
@@ -604,7 +539,10 @@ triggered it.
Callers that care about the precise error details can
use a type switch or a type guard to look for specific
-errors and extract details.
+errors and extract details. For PathErrors
+this might include examining the internal Error
+to see if it is os.EPERM or os.ENOENT,
+for instance.
pkg.MyType should
be named pkg.NewMyType and should return *pkg.MyType.
The implementation of NewTypeName often uses the
-struct allocation idiom.
+struct allocation idiom.
go/src/pkg/os/file.go:
@@ -784,6 +722,81 @@ makes it easy to check that the return value is
exactly as expected.
++Programmers often want their style to be distinctive, +writing loops backwards or using custom spacing and +naming conventions. Such idiosyncracies come at a +price, however: by making the code look different, +they make it harder to understand. +Consistency trumps personal +expression in programming. +
+ ++If a program does the same thing twice, +it should do it the same way both times. +Conversely, if two different sections of a +program look different, the reader will +expect them to do different things. +
+ +
+Consider for loops.
+Traditionally, a loop over n
+elements begins:
+
+for i := 0; i < n; i++ {
+
+
++Much of the time, the loop could run in the opposite order +and still be correct: +
+ +
+for i := n-1; i >= 0; i-- {
+
+
++The convention +is to count up unless to do so would be incorrect. +A loop that counts down implicitly says “something +special is happening here.” +A reader who finds a program in which some +loops count up and the rest count down +will spend time trying to understand why. +
+ +
+Loop direction is just one
+programming decision that must be made
+consistently; others include
+formatting, naming variables and methods,
+whether a type
+has a constructor, what tests look like, and so on.
+Why is this variable called n here and cnt there?
+Why is the Log constructor CreateLog when
+the List constructor is NewList?
+Why is this data structure initialized using
+a structure literal when that one
+is initialized using individual assignments?
+These questions distract from the important one:
+what does the code do?
+Moreover, internal consistency is important not only within a single file,
+but also within the the surrounding source files.
+When editing code, read the surrounding context
+and try to mimic it as much as possible, even if it
+disagrees with the rules here.
+It should not be possible to tell which lines
+you wrote or edited based on style alone.
+Consistency about little things
+lets readers concentrate on big ones.
+