Coding Conventions
This document outlines a collection of guidelines, style suggestions, and tips
for writing code in the different programming languages used throughout the
Kubernetes project.
2 minute read
Code conventions
Bash
- https://google.github.io/styleguide/shell.xml
- Ensure that build, release, test, and cluster-management scripts run on macOS
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 thanstorage.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 saypackage autoscaler
notpackage 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.
- Unless there’s a good reason, the
- Locks should be called
lock
and should never be embedded (alwayslock sync.Mutex
). When multiple locks are present, give each lock a distinct name following Go conventions:stateLock
,mapLock
etc.
- Please consider package name when selecting an interface name, and avoid redundancy. For example,
Testing conventions
- All new packages and most new significant functionality must come with unit tests.
- Significant features should come with integration and/or end-to-end.
- Do not expect an asynchronous thing to happen immediately—do not wait for one second and expect a pod to be running. Wait and retry instead.
Directory and file conventions
- Avoid package sprawl. Find an appropriate subdirectory for new packages.
- Libraries with no appropriate home belong in new package subdirectories of
pkg/util
.
- Libraries with no appropriate home belong in new package subdirectories of
- 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 likePoll
. The full name iswait.Poll
. - All filenames should be lowercase.
- Go source files and directories 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.
- Document directories and filenames should use dashes rather than underscores.
- Go code for normal third-party dependencies is managed using go modules.
Last modified October 28, 2024: Merge pull request #307 from united-manufacturing-hub/fix/ENG-1711/add-port-to-requirements (dd09fce)