← Back to Blog

The Art of Clean Code

Published:
#software-engineering#best-practices#typescript

Writing code is easy. Writing good code is hard. After years of development, here are my thoughts on what makes code truly clean.

Readability First

Code is read far more often than it’s written. Optimize for clarity:

// Less clear
const f = (x: number, y: number) => x > y ? x : y;

// More clear
function getMaximum(a: number, b: number): number {
  return a > b ? a : b;
}

Your future self (and your teammates) will thank you.

Small, Focused Functions

Each function should do one thing well:

  • Single Responsibility: One reason to change
  • Descriptive Names: No need for comments if the name is clear
  • Minimal Parameters: Generally 3 or fewer arguments

Embrace Meaningful Names

Variables, functions, and classes should reveal intent:

  • getUserById is better than get
  • isActive is better than flag
  • calculateTotalPrice is better than calc

Comments Explain “Why”, Not “What”

// Bad: Redundant comment
// Loop through users
users.forEach(user => { ... });

// Good: Explains reasoning
// Skip inactive users to avoid triggering their webhooks
users.filter(u => u.isActive).forEach(user => { ... });

Error Handling Matters

Don’t ignore errors or use empty catch blocks:

// Handle errors explicitly
try {
  await fetchData();
} catch (error) {
  logger.error('Failed to fetch data', { error });
  throw new DataFetchError('Unable to load user data', { cause: error });
}

Consistent Formatting

Use a formatter like Prettier. Don’t waste mental energy on formatting debates:

  • Consistent indentation
  • Predictable structure
  • Team-wide standards

Write Tests

Tests are documentation that never goes out of date:

  • Unit tests for logic
  • Integration tests for interactions
  • E2E tests for critical paths

Refactor Continuously

Don’t wait for the “big rewrite”:

  • Improve code when you touch it
  • Leave it better than you found it
  • Small, incremental improvements compound

Final Thoughts

Clean code isn’t about perfection—it’s about making conscious choices that prioritize maintainability and clarity. Every codebase has technical debt. The goal is to manage it, not eliminate it.

What are your principles for writing clean code?