Skip to content

docs: add Go code style guide for contributors#1046

Open
zhoward-1 wants to merge 2 commits intomainfrom
docs/go-code-style-guide
Open

docs: add Go code style guide for contributors#1046
zhoward-1 wants to merge 2 commits intomainfrom
docs/go-code-style-guide

Conversation

@zhoward-1
Copy link
Copy Markdown
Contributor

Summary

  • Adds docs/contributing/dev/go/code-style.md

Content:

  • Package naming and structure: naming rules, directory layout (cmd/ vs components/), when to use each
  • Interface design: define at use site (not implementation), small single-responsibility interfaces, idempotency documentation, registry pattern for extensible sets — all drawn from actual Backend/Registry/JobQueue code
  • Logging conventions: zap vs controller-runtime logr, which to use where, consistent field names, log level guidance (no Warn)
  • TODO comment format: TODO(#issue): description — explains the CI enforcement and how to comply
  • Test organization: file naming, package foo vs package foo_test, test function naming pattern, mock generation with mamockgen, table-driven tests

All code examples are derived from existing production code (inferenceserver/backends/, scheduler/).

Why

error-handling.md exists and is thorough. Contributors working on package structure, interface design, and logging conventions have no equivalent reference. This was priority 9 in the proposal doc.

Test plan

  • Verify all internal links resolve (error-handling.md, use-go-mocks-in-unit-test.md, manage-go-dependencies.md, testing.md)
  • Confirm mamockgen is the actual mock generator used in the repo
  • Confirm mock subdirectory naming convention (backendsmocks) matches actual generated dirs

🤖 Generated with Claude Code

zhoward-1 and others added 2 commits April 1, 2026 18:46
Covers package naming and directory layout, interface design patterns
(define at use site, small interfaces, idempotency docs, registry
pattern), logging conventions for zap and controller-runtime logr,
TODO comment format enforcement, and test file organization
(naming, table-driven tests, mock generation with mamockgen).
Draws examples from existing Backend/Registry/Reconciler code.

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
File is at docs/contributing/dev/go/ so links to contributing/ root
require ../../, not ../

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant