A new contributor should not have to ask a teammate how to install, run, or understand a project. Start documenting while the project is small: record its purpose, dependencies, setup steps, and unfinished work. A README gives people a starting point; scripts make its instructions repeatable. section 1.3.1 section 2.1 section 2.2
Keep the README useful as the project grows:
- State what the software does and how to install, configure, run, and use it. section 2.1
- Record dependencies, testing steps, troubleshooting notes, examples, and milestones where they help the team. section 2.1
- Point to commands people can run instead of relying on remembered setup steps; mark missing support with a TODO so contributors can see the gap. section 2.2
A small setup contract
For a Go project, a Makefile can define `GO_VERSION :=1.18` and a `setup` target that installs Go and updates the path. The README can then say `sudo make setup` for installation and `sudo make install-go` for an upgrade. A TODO notes that the shown install target still needs macOS support. The commands and the limitation are both visible to the next contributor. section 2.2
Document code as well as setup. Choose names that help readers find a function, then use comments to say what an exported function does and what callers can expect—not to narrate its implementation. Go can generate documentation from comments above package declarations and functions. Run `make static-check` after enabling comment, punctuation, and spelling checks, fix the findings, and merge the improvement with the code. section 5.5
Listing 5.11 \golangci-lint.yml
linters:
enable:
- gosec
- godot #1
- misspell
- stylecheck
linters-settings: #2
stylecheck:
# Select the Go version to target. The default is '1.13'.
go: "1.18"
checks: ["all","ST1*"]
issues:
exclude-use-default: false #3
output:
format: colored-line-number
# print lines of code with issue, default is true
print-issued-lines: false
# print linter name in the end of issue text, default is true
print-linter-name: true
The lint configuration makes comment quality part of a repeatable check, enabling stylecheck, godot, and misspell. section 5.5
