Compare commits
1
Commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
d22642c2b5 |
@@ -1,6 +1,6 @@
|
|||||||
---
|
---
|
||||||
title: Code Styleguide — Go
|
title: Code Styleguide — Go
|
||||||
last_modified: 2026-11-07
|
last_modified: 2026-11-16
|
||||||
---
|
---
|
||||||
|
|
||||||
1. Format Go code with `gofmt` and then `golines -m 77`, through `make fmt`.
|
1. Format Go code with `gofmt` and then `golines -m 77`, through `make fmt`.
|
||||||
@@ -176,7 +176,7 @@ last_modified: 2026-11-07
|
|||||||
them a bit long.
|
them a bit long.
|
||||||
|
|
||||||
1. Use descriptive names for modules and filenames. Avoid generic names like
|
1. Use descriptive names for modules and filenames. Avoid generic names like
|
||||||
`server`. `util` is banned.
|
`server`. The rules for package names are under Naming, below.
|
||||||
|
|
||||||
1. Constructors **must** take a `Params` struct (or `ThingParams` when
|
1. Constructors **must** take a `Params` struct (or `ThingParams` when
|
||||||
`NewThing()` is used), even for a single argument. Named fields in a Params
|
`NewThing()` is used), even for a single argument. Named fields in a Params
|
||||||
@@ -487,6 +487,102 @@ last_modified: 2026-11-07
|
|||||||
releasable". "Releasable" in this context means that it builds and functions
|
releasable". "Releasable" in this context means that it builds and functions
|
||||||
as expected, and that all tests and linting passes.
|
as expected, and that all tests and linting passes.
|
||||||
|
|
||||||
|
# Naming
|
||||||
|
|
||||||
|
Judge a name where it is read. A caller writes the package name, a dot and the
|
||||||
|
exported name, and reads them as one name: `http.Server`, `list.New`.
|
||||||
|
|
||||||
|
## Package names
|
||||||
|
|
||||||
|
1. Name a package for what it provides (`time`, `list`, `http`), because the
|
||||||
|
caller writes that name in front of everything the package exports.
|
||||||
|
|
||||||
|
1. Write a package name in lowercase letters and digits only, with its words
|
||||||
|
run together (`tabwriter`, never `tab_writer` or `tabWriter`), because that
|
||||||
|
is how the standard library spells every package name.
|
||||||
|
|
||||||
|
1. Never name a package `model`, `models`, `util`, `utils`, `common`, `misc`,
|
||||||
|
`helper`, `helpers`, `types`, `interfaces` or `api`, or anything else that
|
||||||
|
says nothing about what is in it: every program has a data model, helpers
|
||||||
|
and types. Name the package for the one thing its code is about; when its
|
||||||
|
code is about several things, split it first (`stringset`, not `util`).
|
||||||
|
|
||||||
|
1. Spell a word out unless its short form is the one everybody already uses
|
||||||
|
(`fmt`, `strconv`), because any other abbreviation has to be decoded.
|
||||||
|
|
||||||
|
1. Never give a package a name that callers want for a variable (`buf`,
|
||||||
|
`count`) or that a widely used standard package has (`log`, `http`, `url`),
|
||||||
|
because every importer then has to rename one of the two. Use a longer name
|
||||||
|
that says which one: `bufio`, `usercount`.
|
||||||
|
|
||||||
|
1. Give a package's directory the package's name, package `main` excepted, so
|
||||||
|
that the import path ends in the name the code uses.
|
||||||
|
|
||||||
|
1. Name a package that supports the tests of one package after that package
|
||||||
|
plus `test` (`storetest`, never `testutil` or `testhelper`), because the
|
||||||
|
name then says whose tests it is for.
|
||||||
|
|
||||||
|
1. Import a package under its own name. Give it a local name only when two
|
||||||
|
imports have the same name or its own name breaks these rules, and use that
|
||||||
|
local name in every file, so that one name always means one package.
|
||||||
|
|
||||||
|
## Exported names
|
||||||
|
|
||||||
|
1. Never repeat the package name inside a longer exported name (`http.Server`,
|
||||||
|
not `http.HTTPServer`; `yamlconfig.Parse`, not
|
||||||
|
`yamlconfig.ParseYAMLConfig`), because the caller has already written it.
|
||||||
|
The type a package is named for may carry the same name on its own:
|
||||||
|
`list.List`, `time.Time`.
|
||||||
|
|
||||||
|
1. Use the same plain name in two packages when it fits both (`bufio.Reader`,
|
||||||
|
`csv.Reader`), because the package name already tells them apart.
|
||||||
|
|
||||||
|
1. Leave the receiver's type out of a method name, and the parameter and result
|
||||||
|
types out of a function name (`(c *Config) WriteTo(w)`, not
|
||||||
|
`WriteConfigTo`), because the signature already states them. Only when two
|
||||||
|
functions differ in nothing but a type does the type go in, at the end:
|
||||||
|
`ParseInt`, `ParseInt64`.
|
||||||
|
|
||||||
|
1. Name a function that returns a value for the value and one that acts for the
|
||||||
|
action (`JobName(key)`, `WriteDetail(w)`), so that a call reads as what it
|
||||||
|
gives or what it does.
|
||||||
|
|
||||||
|
1. Never start a getter with `Get` (`Owner()`, not `GetOwner()`; the setter is
|
||||||
|
`SetOwner()`), because the capital letter already tells the method from the
|
||||||
|
field. A call that goes to a database or the network takes a verb that says
|
||||||
|
so (`Fetch`, `Load`), and `Get` stays only where it is the thing's own word,
|
||||||
|
as in an HTTP GET.
|
||||||
|
|
||||||
|
1. Name a one-method interface for its method plus `er` (`Reader`,
|
||||||
|
`Formatter`), because the name then says the one thing a value of it does.
|
||||||
|
|
||||||
|
1. Give a method that does what a well-known method does that method's name and
|
||||||
|
signature: `String()`, never `ToString()`. Give a method that does anything
|
||||||
|
else another name, because readers and the standard interfaces rely on
|
||||||
|
`Read`, `Write`, `Close` and `String` meaning one thing.
|
||||||
|
|
||||||
|
1. Write an initialism in one case throughout (`ServeHTTP`, `appID`, `URL` or
|
||||||
|
`url`; never `Url`, `Id` or `Http`), because that is how the standard
|
||||||
|
library spells them.
|
||||||
|
|
||||||
|
1. Write a constant in MixedCaps like every other name (`MaxPacketSize`, never
|
||||||
|
`MAX_PACKET_SIZE`), because an all-capitals name is exported whether or not
|
||||||
|
that was meant.
|
||||||
|
|
||||||
|
1. Name an error value `Err` plus what went wrong (`ErrNotFound`) and an error
|
||||||
|
type for what went wrong plus `Error` (`NotFoundError`), because callers
|
||||||
|
know a package's errors by those two forms.
|
||||||
|
|
||||||
|
## Local names
|
||||||
|
|
||||||
|
1. Match a local name's length to the distance between its declaration and its
|
||||||
|
last use (`i`, `r` and `db` across a few lines, a full word or two across a
|
||||||
|
long function), because a reader far from the declaration has only the name.
|
||||||
|
|
||||||
|
1. Name a receiver with one or two letters, the same in every method of its
|
||||||
|
type, never `this`, `self` or `me`, because it appears on nearly every line
|
||||||
|
of those methods.
|
||||||
|
|
||||||
# Other Golang Tips and Best Practices (Optional)
|
# Other Golang Tips and Best Practices (Optional)
|
||||||
|
|
||||||
1. For any internet-facing http server, set appropriate timeouts and limits to
|
1. For any internet-facing http server, set appropriate timeouts and limits to
|
||||||
|
|||||||
Reference in new issue
Block a user