clean-code

Clean Code Principles

Guidance for maintaining clean, readable code that respects human cognitive limits.

Core Principle: Limited Working Memory

Humans can hold approximately 4-7 items in working memory at once. Code must be written with this constraint in mind. Every function, module, and abstraction should minimize the mental load required to understand it.

Function Design

Keep Functions Small and Focused

A function should do one thing and fit in your head:

• Max 20-30 lines as a soft guideline
• Max 3-4 parameters - more indicates the function does too much
• Single level of abstraction - don't mix high-level logic with low-level details

-- BAD: Mixed abstraction levels, too much happening
function process_pod(pod)
  local name = pod.metadata.name
  local ns = pod.metadata.namespace
  local status = pod.status.phase
  if status == "Running" then
    local containers = pod.spec.containers
    for _, c in ipairs(containers) do
      -- 50 more lines of container processing...
    end
  end
  -- format output, handle errors, update state...
end

-- GOOD: Each function handles one concern
function process_pod(pod)
  local info = extract_pod_info(pod)
  if is_running(info) then
    process_containers(pod.spec.containers)
  end
  return format_output(info)
end

Descriptive Names Over Comments

Names should reveal intent. If you need a comment to explain what code does, rename it instead:

// BAD
let t = 86400; // seconds in a day

// GOOD
let seconds_per_day = 86400;

// BAD
fn proc(d: &Data) -> Result  // processes the data

// GOOD
fn validate_and_transform_resource(resource: &Resource) -> Result

Early Returns to Reduce Nesting

Deep nesting forces the reader to track multiple conditions. Use early returns:

-- BAD: Reader must track 3 levels of conditions
function handle_request(req)
  if req then
    if req.valid then
      if req.authorized then
        -- actual logic here, 3 levels deep
      end
    end
  end
end

-- GOOD: Flat structure, exit early
function handle_request(req)
  if not req then return nil end
  if not req.valid then return nil, "invalid" end
  if not req.authorized then return nil, "unauthorized" end

  -- actual logic here, at top level
end