46 lines
1.5 KiB
Markdown
46 lines
1.5 KiB
Markdown
# Development guide
|
|
|
|
IMPORTANT: Read @README.md, @aip.md.
|
|
|
|
## Best practices
|
|
|
|
Do not read generated files, except for debugging purposes.
|
|
|
|
After making a change, check the project for diagostnics, and if applicable, run
|
|
related build and test commands.
|
|
|
|
## Backend/Golang
|
|
|
|
Do not alter go.mod directly, instead, use the CLI tools `go mod tidy`, `go mod
|
|
init`, and so forth.
|
|
|
|
Write tests for all public APIs. Never test a private API; if it feels like we
|
|
need to do that, refactor the code to make the difficult-to-test part a new
|
|
package.
|
|
|
|
Prefer to write clear function and variables names over comments. In general,
|
|
avoid writing comments when the same logic can be communicated with code.
|
|
|
|
Follow https://github.com/golang-standards/project-layout/blob/master/README.md
|
|
for layout
|
|
|
|
The main function should be very small.
|
|
|
|
Prefer to test with real implementations rather than mocks. For example, bring
|
|
up a real HTTP server to test.
|
|
|
|
Generally conform to resource-oriented design describe in
|
|
https://google.aip.dev/general. Read aip.md for a summary. All proto service
|
|
methods should be annotated with google.api.http hints and path variables.
|
|
|
|
## Frontend/Typescript
|
|
|
|
Do not alter package.json directly, instead, use the CLI tool `npm`.
|
|
|
|
Write unit tests for all exported APIs. Never test private APIs. If it feels
|
|
like we need to test private methods, refactor the code to make the
|
|
difficult-to-test part of a new package.
|
|
|
|
Prefer to keep the front-end code minimal. If there is a need to transform data,
|
|
do that on the backend, and add a new API to load the transformed data.
|