Calendar Favorite 1 Streamline Icon:  Mark Your Calendars: The next VSecM Contributor Sync will be on... Thursday, 2024-05-30 at 8:00a Pacific time.
Rating Star 1 Streamline Icon:  Star VMware Secrets Manager to show your support. Help us reach out to even more people with this amazing tech.

ADR-0016: Centralize Magic Words, Numbers, and Configuration Constants in Common Modules

  • Status: accepted
  • Date: 2024-05-12
  • Tags: code-quality, maintainability, readability, configuration

Link Context and Problem Statement

‘Magic’ words and numbers—values with unexplained meaning or context used directly in code—can lead to confusion and errors during development and maintenance.

These values often represent thresholds, specific identifiers, or configuration options that are reused across different parts of the application.

Without a central place to define them, updating these values can become error-prone, and understanding their purpose can be challenging for both new and experienced developers.

The maintainability, readability, and overall management of configuration data are crucial for the long-term health and efficiency of our software projects. In the codebase, ‘magic’ words and numbers—values directly used in code that lack clear context or explanation—can lead to confusion and maintenance challenges.

Additionally, important configuration data like environment variable names often represent system-critical information that is used across various parts of the application. Managing these through hard-coded values scattered throughout the code can result in errors and inconsistencies when changes are made.

Here is an example of how such variables may be defined as constants:

package constants

type Identifier string

// CorrelationId is the identifier for the correlation ID.
// It is used to correlate log messages and other data across
// services while logging.
const CorrelationId Identifier = "correlationId"

type EnvVarName string

const AppVersion EnvVarName = "APP_VERSION"
const VSecMLogLevel EnvVarName = "VSECM_LOG_LEVEL"
const VSecMSafeSpiffeIdPrefix EnvVarName = "VSECM_SAFE_SPIFFEID_PREFIX"
const VSecMSafeEndpointUrl EnvVarName = "VSECM_SAFE_ENDPOINT_URL"
const VSecMKeyGenDecryptMode EnvVarName = "VSECM_KEYGEN_DECRYPT"

type FieldName string

const RootKeyText FieldName = "KEY_TXT"

Link Exceptions

Link URLs and API Endpoints

Given the potential for over-centralization and the specific contextual use of API endpoints within different modules or services, we will exclude API endpoints from being defined in the common constants module. This decision is based on:

  • Reduced Complexity: Keeping API endpoints defined within the modules or services where they are used maintains simplicity and avoids the overhead of managing a large number of rarely changed or highly specific constants.
  • Local Context Clarity: Defining endpoints closer to their usage context helps in understanding and maintaining the service-specific logic without navigating away to a central constants file.

Link Decision Drivers

  • Configuration Management: Centralizing configuration data for easier management.
  • Error Prevention: Reducing the risk of errors and inconsistencies in the codebase.

Link Considered Options

  1. Centralize ‘magic’ words, numbers, and configuration constants in a common module.
  2. Keep ‘magic’ words, numbers, and configuration constants distributed across the codebase.

Link Decision Outcome

Chosen option: “option 1”, because centralizing ‘magic’ words, numbers, and configuration constants in a common module improves maintainability, readability, and consistency across the codebase. It will also make it less error-prone to update these values and provide a clear reference point for developers.

Link Positive Consequences

  • Improved maintainability and readability of the codebase.
  • Reduced risk of errors and inconsistencies in configuration data.
  • Easier management and updating of ‘magic’ words, numbers, and configuration constants.
  • Clear reference point for developers to understand the purpose and context of these values.

Link Negative Consequences

  • Increased complexity in managing the common constants module.
  • Potential for over-centralization leading to confusion or misuse of constants.
  • Possible need for additional documentation to explain the purpose and usage of these centralized constants.
  • Increased dependency on the common constants module for various parts of the application.



Link ADRs

You can view the ADRs by browsing this following list:

edit this page ✏️