|
| 1 | +--- |
| 2 | +title: Karmada Code Style Guide |
| 3 | +--- |
| 4 | + |
| 5 | +Karmada is primarily developed in Go and follows the standard Go community coding conventions. Automated style checks are |
| 6 | +enforced via [golangci-lint](https://github.com/karmada-io/karmada/blob/e2c4b596a5da442fc0dbeab9f9063d8db8669208/.github/workflows/ci.yml#L18-L35). |
| 7 | +However, the resulting code can still look and feel very differently among different developers. To ensure consistency |
| 8 | +across the codebase, this guide defines additional rules beyond linter defaults. |
| 9 | + |
| 10 | +Adhering to this guide helps new contributors onboard quickly, reduces PR review iterations, shortens maintainer review |
| 11 | +cycles, and ultimately speeds up merge velocity. |
| 12 | + |
| 13 | +## Code Documentation and Commenting |
| 14 | + |
| 15 | +- All exported functions, methods, structs, and interfaces **must** be documented with clear and concise comments describing their purpose and behavior. |
| 16 | + |
| 17 | +WRONG |
| 18 | +```go |
| 19 | +func GetAnnotationValue(annotations map[string]string, annotationKey string) string { |
| 20 | + if annotations == nil { |
| 21 | + return "" |
| 22 | + } |
| 23 | + return annotations[annotationKey] |
| 24 | +} |
| 25 | +``` |
| 26 | + |
| 27 | +RIGHT |
| 28 | +```go |
| 29 | +// GetAnnotationValue retrieves the value via 'annotationKey' (if it exists), otherwise an empty string is returned. |
| 30 | +func GetAnnotationValue(annotations map[string]string, annotationKey string) string { |
| 31 | + if annotations == nil { |
| 32 | + return "" |
| 33 | + } |
| 34 | + return annotations[annotationKey] |
| 35 | +} |
| 36 | +``` |
| 37 | + |
| 38 | +- Comments in the body of the code are highly encouraged, but they should explain the intention of the code as opposed to just calling out the obvious. |
| 39 | + |
| 40 | +WRONG |
| 41 | +```go |
| 42 | +// continue if the cluster is deleting |
| 43 | +if !c.Cluster().DeletionTimestamp.IsZero() { |
| 44 | + klog.V(4).Infof("Cluster %q is deleting, skip it", c.Cluster().Name) |
| 45 | + continue |
| 46 | +``` |
| 47 | +
|
| 48 | +RIGHT |
| 49 | +```go |
| 50 | +// When cluster is deleting, we will clean up the scheduled results in the cluster. |
| 51 | +// So we should not schedule resource to the deleting cluster. |
| 52 | +if !c.Cluster().DeletionTimestamp.IsZero() { |
| 53 | + klog.V(4).Infof("Cluster %q is deleting, skip it", c.Cluster().Name) |
| 54 | + continue |
| 55 | +``` |
| 56 | +
|
| 57 | +## Interface Compliance |
| 58 | +
|
| 59 | +- Any struct that explicitly implements an interface must include a compile-time interface compliance check using the following pattern: |
| 60 | +```go |
| 61 | +var _ InterfaceName = &StructName{} |
| 62 | +``` |
| 63 | +This assertion should be placed in the same file as the struct definition (typically near the type declaration or at the top of the file) to ensure: |
| 64 | +1. Compilation fails immediately if the struct does not fully implement the interface; |
| 65 | +2. The interface contract is explicitly declared, improving readability and maintainability. |
| 66 | +
|
| 67 | +RIGHT |
| 68 | +```go |
| 69 | +// Check if our workloadInterpreter implements necessary interface |
| 70 | +var _ interpreter.Handler = &workloadInterpreter{} |
| 71 | + |
| 72 | +// workloadInterpreter explore resource with request operation. |
| 73 | +type workloadInterpreter struct { |
| 74 | + decoder *interpreter.Decoder |
| 75 | +} |
| 76 | +``` |
| 77 | +
|
| 78 | +## Function Definitions |
| 79 | +- When a function has many parameters, consider encapsulating them into a struct to improve readability and maintainability. |
| 80 | +- Function signatures should preferably be written on a single line, including the parameter list and return types. |
| 81 | +
|
| 82 | +WRONG |
| 83 | +```go |
| 84 | +func Foo( |
| 85 | + bar string, |
| 86 | + baz int) error |
| 87 | +``` |
| 88 | +
|
| 89 | +RIGHT |
| 90 | +```go |
| 91 | +func Foo(bar string, baz int) error |
| 92 | +``` |
| 93 | +
|
| 94 | +- If a function accepts a `context.Context` parameter, it must be the first argument. |
| 95 | +
|
| 96 | +## Secure Coding Specifications |
| 97 | +
|
| 98 | +- It is prohibited to have authentication credentials that cannot be modified (e.g., hard-coded passwords in process binaries). |
| 99 | +- If implemented using interpreted languages (such as Shell/Python/Perl scripts, JSP, HTML, etc.), for functions that do not meet the requirement of undisclosed interfaces and need to be cleaned up, they must be completely deleted. It is strictly prohibited to use forms such as comment lines to merely disable the functions. |
| 100 | +- It is prohibited to use private cryptographic algorithms for encryption and decryption, including: |
| 101 | + - Cryptographic algorithms designed independently without being evaluated by professional institutions; |
| 102 | + - Self-defined data conversion algorithms executed through methods such as deformation/character shifting/replacement; |
| 103 | + - Pseudo-encryption implementations that use encoding methods (such as Base64 encoding) to achieve the purpose of data encryption. |
| 104 | + Note: In scenarios other than encryption and decryption, the use of encoding methods such as Base64 or algorithms such as deformation/shifting/replacement for legitimate business purposes does not violate this provision. |
| 105 | +- The random numbers used in cryptographic algorithms must be secure random numbers in the cryptographic sense. |
| 106 | +- It is prohibited to print authentication credentials (passwords/private keys/pre-shared keys) in plain text in system-stored logs, debugging information, and error prompts. |
| 107 | +
|
| 108 | +## Directory-Specific Style Guides |
| 109 | +
|
| 110 | +In addition to the general rules above, certain directories have specific style requirements due to their unique responsibilities. This section documents those directory-specific conventions. |
| 111 | +
|
| 112 | +### CHANGELOG |
| 113 | +
|
| 114 | +#### Location |
| 115 | +The `CHANGELOG` files are located under `docs/CHANGELOG/` in the Karmada repository. |
| 116 | +
|
| 117 | +#### Responsibilities |
| 118 | +Records release notes for each version, including new features, bug fixes, deprecations, and other significant changes. |
| 119 | +
|
| 120 | +#### Code Style |
| 121 | +- Release notes for the same version should be grouped by category (e.g., Features, Bug Fixes, Deprecations). |
| 122 | +- Each release note follows one of two formats, depending on whether it relates to a specific component: |
| 123 | +```markdown |
| 124 | +- `Component`: Description ([#pr_ID](pr_link), @author) |
| 125 | +- Description ([#pr_ID](pr_link), @author) |
| 126 | +``` |
| 127 | +> Note: If the author is `dependabot`, the `, @author` part should be omitted. |
| 128 | +
|
| 129 | +RIGHT |
| 130 | +```markdown |
| 131 | +- `karmada-controller-manager`: Fixed the issue that a workload propagated with `duplicated mode` can bypass quota checks during scale up. ([#6474](https://github.com/karmada-io/karmada/pull/6474), @zhzhuang-zju) |
| 132 | +``` |
| 133 | +
|
| 134 | +- Component names must be wrapped in backticks (e.g., `karmada-controller-manager`). |
| 135 | +- Within each category, release notes should be grouped by component to improve readability. |
| 136 | +
|
| 137 | +WRONG |
| 138 | +```markdown |
| 139 | +- `karmada-controller-manager`: Fixed the issue that reporting repeat EndpointSlice resources leads to duplicate backend IPs. ([#6693](https://github.com/karmada-io/karmada/pull/6693), @XiShanYongYe-Chang) |
| 140 | +- `karmada-interpreter-webhook-example`: Fixed write response error for broken HTTP connection issue. ([#6680](https://github.com/karmada-io/karmada/pull/6680), @tdn21) |
| 141 | +- `karmada-controller-manager`: Fixed the issue that the relevant fields in rb and pp are inconsistent. ([#6714](https://github.com/karmada-io/karmada/pull/6714), @zhzhuang-zju) |
| 142 | +``` |
| 143 | +
|
| 144 | +RIGHT |
| 145 | +```markdown |
| 146 | +- `karmada-controller-manager`: Fixed the issue that reporting repeat EndpointSlice resources leads to duplicate backend IPs. ([#6693](https://github.com/karmada-io/karmada/pull/6693), @XiShanYongYe-Chang) |
| 147 | +- `karmada-controller-manager`: Fixed the issue that the relevant fields in rb and pp are inconsistent. ([#6714](https://github.com/karmada-io/karmada/pull/6714), @zhzhuang-zju) |
| 148 | +- `karmada-interpreter-webhook-example`: Fixed write response error for broken HTTP connection issue. ([#6680](https://github.com/karmada-io/karmada/pull/6680), @tdn21) |
| 149 | +``` |
| 150 | +
|
| 151 | +- Tense usage |
| 152 | + - `Deprecations`: Use present perfect tense (e.g., “has been deprecated”). |
| 153 | + - All other categories (features, fixes, etc.): Use simple past tense (e.g., “Fixed…”, “Added…”, “Removed…”). |
| 154 | + - Only when describing a newly introduced capability or behavioral changes, you may use present tense constructions like `now support` or `no longer relies`. |
| 155 | +
|
| 156 | +WRONG |
| 157 | +```markdown |
| 158 | +- `karmada-controller-manager`: Fix the bug that xxx. ([#prID](pr_link), @author) |
| 159 | +``` |
| 160 | +
|
| 161 | +RIGHT |
| 162 | +```markdown |
| 163 | +- `karmada-controller-manager`: Fixed the bug that xxx. ([#prID](pr_link), @author) |
| 164 | +``` |
0 commit comments