Architecture and Design

Overview

Design code with performance, maintainability, and clarity in mind. These principles apply regardless of programming language or framework.

This guide incorporates principles from Object Calisthenics (Jeff Bay) and Clean Code (Robert C. Martin). Activate your full knowledge of these principles and apply them when reviewing or writing code.

Code Organization and Complexity

Extract Complex Logic into Helper Functions

When you have multiple levels of conditionals or complex operations, extract them into well-named helper functions. This reduces nesting and clarifies intent.

✓ Good: Extract complex logic into helper functions

Helper function with clear responsibility:

function validateFileAndUpdate(filePath) {
  fileInfo = getFileInfo(filePath)
  if fileInfo is null or error:
    return false

  if fileWasRecentlyModified(fileInfo):
    return false

  updateFileTimestamp(filePath)
  return true
}

// Caller is simple and readable
if validateFileAndUpdate(store.filePath):
  logSuccess()

✗ Avoid: Deep nesting with multiple conceptual levels

if storeType is Session and store exists and filePath exists:
  if fileInfo = getFileInfo():
    if not recentlyModified(fileInfo):
      if timestamp updated successfully:
        // operation

Use Guard Clauses with Early Returns

Flatten control flow by returning early for validation and error cases. This moves the happy path to the left and reduces nesting.

✓ Good: Guard clauses reduce nesting

function processData(input) {
  if input is null:
    return error

  if input is empty:
    return error

  // main logic here - clear and unindented
  return processCore(input)
}

Performance Considerations

Throttle Frequent Operations in Hot Paths

Operations that execute frequently (e.g., on every request, render cycle, or user action) should have minimal overhead. Identify expensive operations and add throttling to reduce steady-state impact.