Skip to contentJMRG
ESEN
← All posts

Introduction to Clean Code: Principles for Sustainable Code

clean-codebest-practicessoftware-engineering

Why Does Clean Code Matter?

Imagine inheriting a project where every function has 500 lines, variables are named x, temp, data2, and comments say "this works, don't touch". This scenario is more common than it seems, and it has real costs: hours of debugging, production bugs, and frustrated developers.

Clean code is not just code that works. It's code that communicates intent, that can be maintained by others (including your future self), and that solves problems without creating new ones.

Code as Communication

One of the most important lessons is understanding that code is not just instructions for machines - it's a way to communicate intent to other developers.

Before: Cryptic code

function chb(d: number, m: number, y: number): number {
  return new Date(y, m - 1, d).getTime() - Date.now() / 6e4 * 70;
}

After: Code that communicates intent

const AVG_HEART_RATE_PER_MILLISECOND = 70 / 60000;
/**
 * Calculates heart beats since birth
 * @param birthDay - Day of birth
 * @param birthMonth - Month of birth
 * @param birthYear - Year of birth
 * @returns Estimated number of heartbeats
 */
function calculateHeartBeatsSinceBirth(
  birthDay: number,
  birthMonth: number,
  birthYear: number
): number {
  const birthDate = new Date(birthYear, birthMonth - 1, birthDay);
  const millisecondsSinceBirth = Date.now() - birthDate.getTime();
  return millisecondsSinceBirth * AVG_HEART_RATE_PER_MILLISECOND;
}

Both functions do exactly the same thing, but one clearly communicates its purpose while the other requires deciphering.

The 4 Pillars of Clean Code

mindmap
  root((Clean Code))
    Reliability
      Stability
      Resilience
      Graceful degradation
    Efficiency
      Resources
      Dev time
      Cognitive cost
    Maintainability
      Common patterns
      Consistency
      Clarity
    Usability
      Intuitive APIs
      Descriptive names
      Documentation

1. Reliability

Code must do what it promises, without surprises. This includes three aspects:

  • Stability: Works correctly under different conditions
  • Resilience: Handles unexpected inputs without collapsing
  • Graceful degradation: Maintains basic functionality when advanced features fail
/** Plays audio with fallback to transcript */
function playAudio(): void {
  if (detectAudioMP3Support()) {
    playMP3Track();
  } else {
    showTranscript();
  }
}

2. Efficiency

It's not just about execution speed. Efficiency includes:

  • Optimal resource usage (memory, CPU, network)
  • Development and maintenance time
  • Cognitive cost to understand the code

3. Maintainability

Code is read 10 times more than it's written. For maintainability:

  • Don't stray from common design patterns
  • Be consistent with syntax and presentation
  • Bring clarity to unfamiliar domains

4. Usability

APIs and functions should be intuitive.

Before: Confusing API with ambiguous parameters

function checkIsNewYear(
  configuration: unknown,
  filter: unknown,
  formatter: unknown,
  MDY: unknown,
  SMH: unknown
): unknown { }

After: Clear and focused API

/** Checks if a date is New Year's Day */
function isNewYear(date: Date): boolean {
  return date.getMonth() === 0 && date.getDate() === 1;
}

The Enemies of Clean Code

The Programmer's Ego

Ego is a double-edged sword. The positive side drives us toward excellence, but the negative side leads us to write code to impress rather than maintainable code.

Before: Exotic syntax

const rounded = ~~65.7;

After: Clarity over brevity

const rounded = Math.floor(65.7);

Maturity in programming is reflected in prioritizing readability over skill demonstration.

The Abstraction Balance

Finding the right level of abstraction is a balancing act:

  • DRY (Don't Repeat Yourself): If you repeat yourself, you need to abstract
  • YAGNI (You Aren't Gonna Need It): Don't over-abstract before it's needed

The sweet spot lies between both extremes.

Conclusion

Clean code is not a luxury - it's a necessity for sustainable projects. The four pillars (Reliability, Efficiency, Maintainability, Usability) form the foundation of all professional code.

In the next article we'll explore the SOLID Principles, the foundation of clean architecture that allows us to apply these concepts in a structured way.

Based on "Clean Code in JavaScript" by James Padolsey and principles established by Robert C. Martin.