k3s/docs/contrib/code_conventions.md
Jossemar Cordero 0a56b29dec
Add contributors documentation (#5154)
Add contributor's documentation addressing: 
- Git workflow and CI
- Coding conventions in Go and POSIX shell languages
- Development setup and tooling involved
2022-02-28 11:56:23 -06:00

2.1 KiB

Code conventions

POSIX shell

Go

  • Go Code Review Comments
  • Effective Go
  • Know and avoid Go landmines
  • Comment your code.
    • Go's commenting conventions
    • If reviewers ask questions about why the code is the way it is, that's a sign that comments might be helpful.
  • Command-line flags should use dashes, not underscores
  • Naming
    • Please consider package name when selecting an interface name, and avoid redundancy. For example, storage.Interface is better than storage.StorageInterface.
    • Do not use uppercase characters, underscores, or dashes in package names.
    • Please consider parent directory name when choosing a package name. For example, pkg/controllers/autoscaler/foo.go should say package autoscaler not package autoscalercontroller.
      • Unless there's a good reason, the package foo line should match the name of the directory in which the .go file exists.
      • Importers can use a different name if they need to disambiguate.

Directory and file conventions

  • Avoid general utility packages. Packages called "util" are suspect. Instead, derive a name that describes your desired function. For example, the utility functions dealing with waiting for operations are in the wait package and include functionality like Poll. The full name is wait.Poll.
  • All filenames should be lowercase.
  • All source files and directories should use underscores, not dashes.
    • Package directories should generally avoid using separators as much as possible. When package names are multiple words, they usually should be in nested subdirectories.

Testing conventions

Please refer to TESTING.md document.