Clearly document the intended purpose, scope limitations, and design decisions in your code. For all exported types, functions, and variables, provide comprehensive comments explaining their purpose, usage patterns, expected behavior, and any deliberate limitations.
Clearly document the intended purpose, scope limitations, and design decisions in your code. For all exported types, functions, and variables, provide comprehensive comments explaining their purpose, usage patterns, expected behavior, and any deliberate limitations.
When documenting code:
Always update documentation when modifying code behavior, and ensure comments accurately reflect current usage patterns. This helps prevent misunderstandings and improves maintainability.
Example:
// ociImageManifestSizeLimit is the maximum size of artifact manifest (aka "image
// manifest") we'll accept. This 4MiB value matches the recommended limit for
// repositories to accept on push from the OCI Distribution v1.1 spec:
// https://github.com/opencontainers/distribution-spec/blob/v1.1.0/spec.md#pushing-manifests
const ociImageManifestSizeLimitMiB = 4
// providerIterationIdentical performs a limited comparison of HCL expressions
// to determine if they are syntactically identical. This function is intentionally
// limited to simple references and function calls with simple reference arguments.
// All other expression types will return false by default, as this function is not
// expected to handle every possible HCL expression type.
func providerIterationIdentical(a, b hcl.Expression) bool {
// implementation...
}
// EvalContextWithParent creates an evaluation context derived from the given parent
// context. This allows the new context to inherit values from its parent while
// adding or overriding specific values. This is particularly useful for nested
// evaluations like module calls where child contexts need access to parent variables
// but also define their own local values.
func (s *Scope) EvalContextWithParent(...) {...}
// On Windows, we use 0777 permissions instead of 0755 because Windows
// doesn't have the same permission model and these bits get ignored
if runtime.GOOS == "windows" {
// Windows-specific behavior
}
Enter the URL of a public GitHub repository