When in Go, Do As Gophers Do [slides] #35

New Issue

jeff · 2021-06-01T22:43:17Z

jeff commented

2021-06-01 22:43:17 +00:00

Go should be idiomatic (concise, articulate, simple API, precise comments, readble).

Readable code == easy to recognize, less burden for brain.
Both writer and reader should have readability skills.
Go is very simple (lang spec is about 50 pages)

Check error with regexp.MustCompile.
Must should be used only in initialization (package var or init()).
Raw string literal makes it easy to read regexp.
-- slide 9

Do not ignore errors when using defer to close.
-- slide 11

Return errors as error values.
-- slide 12

Don't use panic.
But when you do, use it only within the package, and return error with catching it by recover.
-- slide 14

Compile time checks if type implements an interface: var _ scan.Writer = (*ColumnWriter)(nil)
This avoids a runtime panic.
-- slide 17

Organize fields into groups. For example, group a mutex with a type it locks.
-- slide 21

Keep code on one line
-- slide 23

Use concise, accurate names!
-- slide 24

Receiver names should be less than 3 letters.
-- slide 24

Keep the normal code path at a minimal indentation.
-- slide 27

Use switch instead of if-else tree
-- slide 31

Use time.Duration (flag.Duration) rather than int or float to represent time duration.
-- slide 33

Don't create yet-another assert function. Use existing programming language features.
-- slide 39

Write an example test rather than writing how to use API in a doc comment.
-- slide 39

Write package comment. Write command comment in main package.
Write comments on exported names.
Doc comment should be a complete sentence that starts with the name being declared.
-- slide 41

Important to choose a good package name.

e.g. package util is not good name, since most packages are utilities of something.
Make API simple.

Use multiple returns. Don't use pointers as output parameters.
Don't use pointer to slice, map, chan or interface.
Return error as error: don't panic
Implement common interfaces (fmt.Stringer, io.Reader and so on) if they match your code.
Use interfaces for parameters. They makes it easier to test. e.g.: If a function reads from a file, use io.Reader as a parameter instead of *os.File.
Prefer synchronous API to async API: refrain from using chan across package boundary.
Clients can easily run synchronous API concurrently with goroutine and chan.
-- slide 42

Go should be idiomatic (concise, articulate, simple API, precise comments, readble). Readable code == easy to recognize, less burden for brain. Both writer and reader should have readability skills. Go is very simple (lang spec is about 50 pages) Check error with regexp.MustCompile. Must should be used only in initialization (package var or init()). Raw string literal makes it easy to read regexp. -- slide 9 Do not ignore errors when using defer to close. -- slide 11 Return errors as error values. -- slide 12 Don't use panic. But when you do, use it only within the package, and return error with catching it by recover. -- slide 14 Compile time checks if type implements an interface: `var _ scan.Writer = (*ColumnWriter)(nil)` This avoids a runtime panic. -- slide 17 Organize fields into groups. For example, group a mutex with a type it locks. -- slide 21 Keep code on one line -- slide 23 Use concise, accurate names! -- slide 24 Receiver names should be less than 3 letters. -- slide 24 Keep the normal code path at a minimal indentation. -- slide 27 Use switch instead of if-else tree -- slide 31 Use time.Duration (flag.Duration) rather than int or float to represent time duration. -- slide 33 Don't create yet-another assert function. Use existing programming language features. -- slide 39 Write an example test rather than writing how to use API in a doc comment. -- slide 39 Write package comment. Write command comment in main package. Write comments on exported names. Doc comment should be a complete sentence that starts with the name being declared. -- slide 41 Important to choose a good package name. e.g. package util is not good name, since most packages are utilities of something. Make API simple. Use multiple returns. Don't use pointers as output parameters. Don't use pointer to slice, map, chan or interface. Return error as error: don't panic Implement common interfaces (fmt.Stringer, io.Reader and so on) if they match your code. Use interfaces for parameters. They makes it easier to test. e.g.: If a function reads from a file, use io.Reader as a parameter instead of *os.File. Prefer synchronous API to async API: refrain from using chan across package boundary. Clients can easily run synchronous API concurrently with goroutine and chan. -- slide 42

Sign in to join this conversation.