Add a basic style guide

1 files changed, 86 insertions, 0 deletions

diff --git a/STYLE.md b/STYLE.md
new file mode 100644
index 00000000..39ef9ff1
--- /dev/null
+++ b/STYLE.md
@@ -0,0 +1,86 @@
+# Style guide
+
+These only really document things that the linter won't check.
+
+## Symbol naming
+
+Try to avoid package aliases.
+`object/store` should simply be imported implicity as `store`,
+`object/id` as `id`, `object/typ` as `typ`, etc.
+
+Avoid letting local variables shadow an imported package.
+
+Name things like `loose.Loose` rather than `loose.Store`.
+
+## File organization
+
+Each package should have a `doc.go`.
+
+Usually also a `<pkg>.go` with
+the package's central type, `New`, `Close`, etc.
+
+Options structs should be close to `New`.
+There should not be an `options.go`.
+
+## Sizes
+
+Sizes are typically `uint64`.
+Use `intconv` for conversions where necessary.
+
+**TODO:** revisit this and consider whether to make sizes `int`.
+
+## Comments
+
+Use semantic line breaks,
+breaking at sentence ends and major clause boundaries.
+
+## Contract labels
+
+See the `doc.go` at the root of the `furgit` package.
+
+## Tests
+
+Test file base-names are `_test`
+appended to the base-name of the file
+whose functionality is being tested.
+
+`roundtrip_test.go` is used
+for roundtrip tests with ourselves.
+
+`helpers_test.go` is used
+for helpers shared between many tests.
+
+`testgit` mainly wraps plumbing commands from git.
+Non-git commands may be added in the future.
+
+For things that may plausibly depend on object formats:
+
+```go
+for _, objectFormat := range id.SupportedObjectFormats() {
+	t.Run(objectFormat.String(), func(t *testing.T) {
+		// Stuff.
+	})
+}
+```
+
+## Errors
+
+See the `errs` package for some guidance on globally common errors.
+
+Define sentinel errors
+for genuinely distinct and reasonably matchable conditions.
+
+Error stings should begin
+with our current package path starting at the module root,
+such as `object/store/packed: whatever`.
+
+Non-sentinel error types should only be defined for cases where
+it is reasonable to expect callers to act on the information.
+
+Underlying errors should almost always be wrapped and passed along.
+For cases where our own sentinel error is reasonable to match on, use
+`fmt.Errorf("%w: %w", ErrOurSentinal ,err)`.
+Otherwise, use
+`fmt.Errorf("path/to/our/package: optionally some context: %w", err)`.
+
+