When working on a project, I find myself repeatedly asking the question: "Is this the best way to do this?" This is the constant refrain that runs through my mind as I navigate the process of creating abstractions, API contracts, generics, mixins, adapters, and other architectural elements.
Just yesterday, I was working on some Terraform infrastructure code and doing a code review with a senior member of the team. During the review, they posed a simple question that gave me pause:
"Do you understand the difference between 'looks good' and 'is good'?"
At first, I thought this was their way of telling me that my code wasn't good enough. However, after reflecting on it for a while, I began to discern a deeper meaning in their question.
Looks good.
Making a code look good is easy.
module "label" {
source = "./modules/label"
tags = var.tags
namespace = var.namespace
name = var.name
stage = var.stage
delimiter = var.delimiter
attributes = compact(concat(var.attributes, ["cluster"]))
}
module "vpc" {
source = "./modules/vpc/"
tags = local.tags
namespace = module.label.namespace
name = module.label.name
stage = module.label.stage
cidr_block = var.cidr_block
}
This code may appear neat and visually appealing. Someone who stumbles upon this Terraform code might say it is beautifully written and likely copied from a template provided by a popular Terraform module provider, such as CloudPosse.
However, this does not necessarily mean the code is "good." At least, not on the inside. One could argue that the only thing that truly matters is the exported interface of the module, and the underlying complexity of the implementation may be irrelevant.
While the code may look clean and organized on the surface, the actual quality and maintainability of the codebase depend on factors beyond just its aesthetics. The complexity of the logic, the efficiency of the implementations, the robustness of the error handling, and the overall alignment with the project's requirements are all important considerations that cannot be fully assessed based on the appearances alone.
In software development, it is important to strike a balance between the visual appeal and the underlying quality of the codebase. Code that looks "beautiful" on the outside but is convoluted or difficult to understand on the inside may still pose challenges for long-term maintenance and future enhancements. The true measure of "good" code should encompass both its external presentation and its internal structure and implementation.
locals {
defaults = {
label_order = ["namespace", "stage", "environment", "name", "attributes"]
delimiter = "-"
replacement = ""
# The `sentinel` should match the `regex_replace_chars`, so it will be replaced with the `replacement` value
sentinel = "~"
attributes = [""]
}
# The values provided by variables superceed the values inherited from the context
enabled = var.enabled
regex_replace_chars = coalesce(var.regex_replace_chars, var.context.regex_replace_chars)
name = lower(replace(coalesce(var.name, var.context.name, local.defaults.sentinel), local.regex_replace_chars, local.defaults.replacement))
namespace = lower(replace(coalesce(var.namespace, var.context.namespace, local.defaults.sentinel), local.regex_replace_chars, local.defaults.replacement))
environment = lower(replace(coalesce(var.environment, var.context.environment, local.defaults.sentinel), local.regex_replace_chars, local.defaults.replacement))
stage = lower(replace(coalesce(var.stage, var.context.stage, local.defaults.sentinel), local.regex_replace_chars, local.defaults.replacement))
delimiter = coalesce(var.delimiter, var.context.delimiter, local.defaults.delimiter)
label_order = length(var.label_order) > 0 ? var.label_order : (length(var.context.label_order) > 0 ? var.context.label_order : local.defaults.label_order)
additional_tag_map = merge(var.context.additional_tag_map, var.additional_tag_map)
# Merge attributes
attributes = compact(distinct(concat(var.attributes, var.context.attributes, local.defaults.attributes)))
# code removed for clarity
}
This is what the label module code looks like on the inside. It's a real mess of Terraform code that would be very challenging to maintain. Although I understand the purpose of each function and local variable here, trying to make edits after being away from this codebase for a month would likely require several minutes to reorient myself and figure out the implementation.
But can this code truly be made "good"?
To improve this, we must first focus on simplifying it. Before proceeding, I'd like to reference the "Zen of Python" principle:
Simple is better than complex.
Complex is better than complicated.
The key distinction here is that complexity, while not ideal, can be justified if it is necessary to accomplish a task. Complication, on the other hand, simply means the code is disorderly and difficult to understand without necessity.
In the case of this label module, the current implementation appears to be overly complicated, rather than appropriately complex. To make this code "good," the focus should be on reducing the complication and unnecessary complexity, breaking down the logic into more modular and understandable components.
Complex vs Complicated
Complexity means that something is hard to understand for a reason, because it requires you to study the complexity, and there is no pragmatic way to avoid it. Compilers might be complex for a programmer because they accomplish a complex job. The nature of compilers is inherently hard to understand, so it cannot be reduced to simpler elements.
Complication means something is difficult to understand and disorderly. In other words, it's a mess. Although this is subjective, one could argue that Helm templates are complicated. However, complicated things can be simplified into simpler and more maintainable components using tools like Kustomize or domain-specific languages (DSLs) like Jsonnet.
The key difference is that complexity arises from the inherent nature of a system, while complication is more about the disorder and difficulty in understanding something. Complexity cannot be easily reduced, while complicated things can often be simplified through the use of appropriate tools and techniques.
Is Good
For something to become good, it must possess a good internal mechanisms and external interface. The code must be maintainable.
In the above example: The sheer number of variables and the nested conditional logic can make the code complex and potentially difficult to maintain or extend in the future, especially for larger or more complex software projects.
In summary, while the code "looks good" in terms of its structure, readability, and adherence to coding best practices, the statement "is good" requires a more in-depth evaluation of the code's actual functionality, performance, and overall quality, which cannot be determined solely from the provided code snippet. A comprehensive assessment of the code's suitability, robustness, and alignment with the software's requirements would be necessary to determine whether the code "is good" or not.
