The following policies are oriented to promote the following:
- Correctness
- Consistency
- Simplicity
- Performance
Note that performance is dead last. We address performance issues only when they arise, and never before they are actually a problem for someone. Optimizing for performance generally means increasing complexity, which is a trade off that must be weighed as part of design.
It is much better to have a simple design that is easy for anyone to debug, than a performant design that is difficult to debug. It is better to bear the keystroke cost of clear code upfront, than bear the cost of increased time spent debugging later.
DONT MAKE THINGS EASY TO DO, MAKE THEM EASY TO UNDERSTAND.
- SOLID Go Design by Dave Cheney
- Data and Semantics by Bill Kenedy
- For Range Semantics by Bill Kenedy
- Interface Values are Valueless by Bill Kenedy
- On Packaging by Bill Kenedy
- On Logging by Bill Kenedy
- Ardan Labs Go Training repo
- Go and SQLite by David Crawshaw
Do the following before committing:
- Ensure the code builds using
make. - Always run
go mod tidybefore committing your code and include changes togo.modandgo.sumto ensure reproducible builds.
Commit messages allow for developers to quickly and concisely review changes. Bad commit messages force developers to look at the code and wonder why a change was made.
Commit messages should follow these conventions:
- Separate subject from body with a blank line
- Limit the subject line to 50 characters (as best as possible)
- Capitalize the subject line
- Do not end the subject line with a period
- Use the imperative mood in the subject line
- Wrap the body at 72 characters
- Use the body to explain what and why vs. how
Most of those are self explanatory but it is recommended that everyone at least review the links for 5 and 7.
We generally follow use a Git Flow branching model. The two major long running branches are:
develop- where the action happens, you probably want to start from heremaster- latest official release, you'll only need this when tracking down an open bug on the release
These two branches shall never be rebased or --force pushed.
Other transient branches shall use the following naming conventions
feature/ABC- long running features under development, generally "owned" by one developer and only pushed to share for code reviews, regularly rebased ondevelopand later deletedrelease/vX.X.X- where the next release is prepared and reviewed, based ondevelop, deleted after merging intomasterand back intodevelophotfix/DEF- where a bugfix for the current release is prepared and reviewed, based onmaster, deleted after merging back intomasterand intodevelop
When working on your own fork, please always rebase onto whatever branch you
intend to make your PR against, and never merge from the base branch (master
or develop) to your feature.
Use the official gofmt tool. It is highly recommended to run gofmt on every save, as this will always catch any syntax errors and ensure consistent formatting. Virtually every IDE and code editor has a plugin that runs gofmt on save.
Do not commit code that has not been run through the formatter.
Please limit line length to 79 characters max to avoid the need for horizontal scrolling. This also applies to comments. Indented comments must still limit the total line length. Most everything in golang can be broken up across multiple lines to properly limit line length.
The line length max for many modern editors are set to 80 characters max now. But the default in vim is 79 for historical reasons, and so this will be perpetuated in this project as well.
The one exception to the max line length are string literals. In order to allow string literals to be easily searched for in the codebase, these should not be broken up across lines. However always insert a newline before the string literal declaration if this allows the line length rule to be respected.
Comments must respect line length rules (see above). Comments should be used to document exported APIs, and explain non-obvious or complex code.
Comments must be complete english sentences. They should be concise and precise. In general, they should explain the intent or high level behavior of code, and only explain non-obvious implementation details or design decisions.
Comments must be kept up to date with the code they describe. When you change code, you must review the comments for discrepancies.
When comments describe behavior you must not change the behavior, as this represents an API level change. Such changes must be discussed and well understood so that any code depending on the behavior can be updated.
Importing external code should be done with care. Imports should be evaluated on test coverage, recent development activity, documentation, and code quality. All external code that is called should be read and understood.
Always run go mod tidy before committing your code.
Packages should provide something useful and specific, not just contain
things. Packages named common, utils, and the like are prohibited.
When intentionally declaring a variable with its zero value, use the var
declaration syntax.
var x intOnly use the short declaration syntax := when declaring AND initializing a
variable to a non-zero value.
y := Type{Hello: "World"}
x, err := computeX()Never do this: x := Type{}
Errors must always be checked, even if it is extremely unlikely, or guaranteed
not to occur. Most errors should cause fatd to cleanly exit. Only a few
exceptions to this rule:
- network server errors like 500 may be retried
- transaction validation errors, named
txErrby convention
Never report normal errors by panicking.
Panics represent a program integrity error. A program integrity error is when the program does something that is or should be impossible, or never happen.
Examples of integrity issues:
- An out of bounds array or slice access or write
- A nil ptr dereference
- A function that must only ever be used in a certain way, with valid inputs. e.g. regexp.MustCompile
The idea of an integrity error, is that when the program is written correctly, this should never occur. So if this occurs, the program is misusing something critical.
If you panic on an error, you should explain in comments why the error represents an integrity issue, if it is not exceedingly obvious.
Interfaces define behavior, not data. Do not use interfaces to represent data. Interfaces should describe what something does, not what it is.
As a general rule, you probably don't need an interface. Create the concrete type first and discover the appropriate interfaces later when you refactor to de-duplicate code that needs to do the same thing to more than one type.
Factory functions construct and initialize a type and by convention start with
the word New.
Only create factory functions for types where the initialization/set-up is not possible or obvious from outside the package.
Do not simply create factory functions out of convenience. It is preferred that types that can be initialized by the user, are left to the user to initialize.
Factory functions must follow the data semantics of the type. See Pointer/Value semantics above.
You probably don't need to use a goroutine to solve the problem. Always write a serialized solution first, evaluate performance, and only then can a concurrent solution be considered.
Only main, engine, and srv get to log. No other package may log. Other packages must return errors up to the caller.