Functions should have thorough documentation that follows Go conventions and explains both the "what" and "why" of the code. This includes: 1. **Proper Go doc format**: Start function comments with the function name, e.g., "GetSecretByName returns the Secret..." instead of "Returns the Secret..."
Functions should have thorough documentation that follows Go conventions and explains both the “what” and “why” of the code. This includes:
Proper Go doc format: Start function comments with the function name, e.g., “GetSecretByName returns the Secret…” instead of “Returns the Secret…”
Explain complex logic: Add explanatory comments for non-obvious code sections that describe why the logic exists, not just what it does.
Document all parameters and return values: Provide clear descriptions of what each parameter represents and what the function returns, especially for complex functions with multiple return values.
Include context and intent: Explain the purpose and use cases of the function, particularly for complex business logic.
Example of good documentation:
// alreadyAttemptedSync is meant to help the caller understand whether an identical sync operation
// has been attempted, to avoid excessively retrying the exact same sync operation.
//
// alreadyAttemptedSync returns true if either 1) newRevisionHasChanges is true and the most recently
// synced revision(s) exactly match the given desiredRevisions, 2) newRevisionHasChanges is false and
// the most recently synced app source configuration matches exactly the current app source configuration,
// or 3) the most recent operation state is missing a sync result but the sync phase is completed.
//
// TODO: remove the last two return parameters, since they're effectively just aliases for fields
// on the app object.
func alreadyAttemptedSync(app *appv1.Application, desiredRevisions []string, newRevisionHasChanges bool) (bool, []string, synccommon.OperationPhase) {
// If pruning is enabled and the app is *not* allowed to have an empty desired state,
// we need to ensure we're not about to accidentally wipe out all resources.
// This is a safety mechanism to prevent full deletion due to automation errors (e.g., empty Git path).
if app.Spec.SyncPolicy.Automated.Prune && !app.Spec.SyncPolicy.Automated.AllowEmpty {
// ... implementation
}
}
Well-documented code reduces cognitive load for reviewers and future maintainers, making the codebase more accessible and maintainable.
Enter the URL of a public GitHub repository