Clean Code Principles That Stand the Test of Time

"Any fool can write code that a computer can understand. Good programmers write code that humans can understand." — Martin Fowler

Clean code isn't about perfection. It's about writing code that's easy to understand, modify, and maintain. Here are the principles that matter most.

1. Meaningful Names

Names should reveal intent. If a name requires a comment, it's wrong.

// ❌ Bad: What is 'd'?
const d = new Date();

// ✅ Good: Intent is clear
const currentDate = new Date();

// ❌ Bad: Single-letter variables (except loop counters)
function calc(a, b, c) {
  return a * b + c;
}

// ✅ Good: Descriptive parameters
function calculateTotalPrice(quantity, unitPrice, tax) {
  return quantity * unitPrice + tax;
}

Naming Guidelines

• Boolean variables: Use is/has/can prefix (isValid, hasPermission)
• Functions: Use verbs (getUserData, calculateTotal)
• Classes: Use nouns (User, PaymentProcessor)
• Constants: Use UPPER_SNAKE_CASE (MAX_RETRIES)
• Avoid: Hungarian notation, abbreviations, number suffixes (data1, data2)

2. Functions Should Do One Thing

Single Responsibility Principle applied to functions.

// ❌ Bad: Does too much
function processUserRegistration(email, password) {
  // Validate email
  if (!/^[^\s@]+@[^\s@]+\.[^\s@]+$/.test(email)) {
    throw new Error('Invalid email');
  }
  
  // Hash password
  const hashedPassword = bcrypt.hashSync(password, 10);
  
  // Save to database
  const user = await db.insert({ email, password: hashedPassword });
  
  // Send welcome email
  await sendEmail(email, 'Welcome!', 'Thanks for registering...');
  
  // Log event
  logger.info('User registered', { userId: user.id });
  
  return user;
}

// ✅ Good: Separated concerns
async function registerUser(email, password) {
  validateEmail(email);
  const hashedPassword = hashPassword(password);
  const user = await saveUser(email, hashedPassword);
  await sendWelcomeEmail(user.email);
  logRegistration(user.id);
  return user;
}

3. Keep Functions Small

Aim for 10-20 lines max. If it doesn't fit on one screen, it's too long.

// ❌ Bad: 100+ line function
function generateReport(data) {
  // 100 lines of nested loops, conditionals, and formatting...
}

// ✅ Good: Extracted smaller functions
function generateReport(data) {
  const filtered = filterRelevantData(data);
  const sorted = sortByDate(filtered);
  const formatted = formatForDisplay(sorted);
  return createPDF(formatted);
}

4. Avoid Deep Nesting

Every level of indentation makes code harder to read.

// ❌ Bad: Arrow of doom
function processOrder(order) {
  if (order) {
    if (order.items.length > 0) {
      if (order.user) {
        if (order.user.hasPaymentMethod) {
          if (order.total > 0) {
            // Finally do something...
          }
        }
      }
    }
  }
}

// ✅ Good: Guard clauses
function processOrder(order) {
  if (!order) return;
  if (order.items.length === 0) return;
  if (!order.user) return;
  if (!order.user.hasPaymentMethod) return;
  if (order.total <= 0) return;
  
  // Do something...
}

5. Don't Repeat Yourself (DRY)

// ❌ Bad: Duplicated logic
function createUser(data) {
  const user = { ...data };
  user.createdAt = new Date().toISOString();
  user.updatedAt = new Date().toISOString();
  return user;
}

function updateUser(id, data) {
  const user = { ...data };
  user.updatedAt = new Date().toISOString();
  return db.update(id, user);
}

// ✅ Good: Extracted common logic
function addTimestamps(data, isNew = false) {
  const now = new Date().toISOString();
  return {
    ...data,
    ...(isNew && { createdAt: now }),
    updatedAt: now,
  };
}

function createUser(data) {
  return addTimestamps(data, true);
}

function updateUser(id, data) {
  return db.update(id, addTimestamps(data));
}

6. Error Handling

Don't ignore errors. Handle them gracefully.

// ❌ Bad: Silent failure
async function getUser(id) {
  try {
    return await db.query('SELECT * FROM users WHERE id = ?', [id]);
  } catch (error) {
    return null;  // Error lost forever!
  }
}

// ✅ Good: Proper error handling
async function getUser(id) {
  try {
    return await db.query('SELECT * FROM users WHERE id = ?', [id]);
  } catch (error) {
    logger.error('Failed to fetch user', { userId: id, error });
    throw new DatabaseError(`User ${id} not found`, { cause: error });
  }
}

7. Comments: Code Should Explain Itself

// ❌ Bad: Comment states the obvious
// Increment i
i++;

// Add 1 to total
total = total + 1;

// ❌ Bad: Comment explains bad code
// Check if user is admin (role 1) or super admin (role 2)
if (user.role === 1 || user.role === 2) { }

// ✅ Good: Self-explanatory code (no comment needed)
if (user.isAdmin() || user.isSuperAdmin()) { }

// ✅ Good: Comment explains WHY, not WHAT
// Use exponential backoff to avoid overwhelming the API during outages
await retryWithExponentialBackoff(apiCall);

When Comments Are Useful

• Explain why a non-obvious solution was chosen
• Warn about consequences or gotchas
• TODO/FIXME for technical debt
• Document complex algorithms
• Legal notices or attribution

8. Consistent Formatting

Use a formatter. Don't debate style manually.

// Use Prettier, Black, gofmt, etc.
// .prettierrc
{
  "semi": true,
  "singleQuote": true,
  "tabWidth": 2,
  "trailingComma": "es5"
}

9. SOLID Principles (OOP)

Single Responsibility

// ❌ Bad: Class does too much
class User {
  save() { /* DB logic */ }
  sendEmail() { /* Email logic */ }
  generateReport() { /* Report logic */ }
}

// ✅ Good: Separated concerns
class User { /* User data */ }
class UserRepository { save() { } }
class EmailService { sendEmail() { } }
class ReportGenerator { generate() { } }

Open/Closed Principle

// ❌ Bad: Modify class for new payment methods
class PaymentProcessor {
  process(type) {
    if (type === 'card') { /* card logic */ }
    else if (type === 'paypal') { /* paypal logic */ }
    // Add more if statements for each new method...
  }
}

// ✅ Good: Open for extension, closed for modification
class PaymentProcessor {
  constructor(paymentMethod) {
    this.method = paymentMethod;
  }
  process() {
    return this.method.pay();
  }
}

class CardPayment { pay() { /* card logic */ } }
class PayPalPayment { pay() { /* PayPal logic */ } }
class CryptoPayment { pay() { /* crypto logic */ } }

10. Test Your Code

Clean code is tested code.

// Write testable code
function calculateDiscount(price, discountPercent) {
  return price * (discountPercent / 100);
}

// Easy to test
test('calculates 10% discount correctly', () => {
  expect(calculateDiscount(100, 10)).toBe(10);
});

Code Smells to Avoid

• Long functions (>50 lines)
• Long parameter lists (>3 parameters — use objects)
• God classes (classes that do everything)
• Dead code (unused functions/variables)
• Magic numbers (unexplained constants)
• Premature optimization (optimize when needed, not "just in case")

The Boy Scout Rule

"Leave the code cleaner than you found it."

Every time you touch code:

• Fix small issues you notice
• Improve variable names
• Extract duplicated logic
• Add missing tests

Conclusion

Clean code isn't about following rules blindly. It's about making code easier for humans (including your future self) to understand and maintain.

Want an expert review of your code quality? Get a code quality audit and receive specific recommendations for improvement within 24 hours.