Why Clean Code Matters: Lessons from Uncle Bob

Software is everywhere. Almost every part of our lives — from banking to maps to music — depends on it. And when software fails, it can cost money, waste time, or even cause real harm. As developers, that means we carry a great responsibility — the way we write code truly matters.

Uncle Bob (Robert C. Martin), a renowned software engineer, instructor, and author, reminds us that clean code is more than just style — it’s about communication. Code is read far more often than it’s written, so clarity, consistency, and simplicity are essential.

In this article, inspired by Uncle Bob’s Clean Code lessons on YouTube and Ryan McDermott’s JavaScript adaptation (clean-code-javascript), I created a quick and practical guide, blending my notes on these timeless principles to help improve your code.

Naming (for functions and variables)

Names are the first level of communication in your code. They should clearly describe what a variable or function represents or does.

• Use meaningful, descriptive names that reveal intent.
• A variable name should be proportional to its scope — short names for short scopes (like loops), longer names for broader contexts.
• For functions, use the opposite logic: if a function is called often, keep its name short; if it’s specific or used less frequently, make it more descriptive.
• Stick to a consistent vocabulary across the codebase — avoid mixing terms like “user”, “client”, and “customer” if they refer to the same entity.
• Good formatting is crucial and should be applied consistently throughout the code.
• Always strive to remove dead or duplicated code to keep your codebase clean.

// BAD
function currentDateFormattedBasedOnLocale(l) {
  return new Date().toLocaleDateString(l);
}

const d_ir = currentDateFormattedBasedOnLocale('en-IE');
const dtUs = currentDateFormattedBasedOnLocale('en-US');

// GOOD
function formatCurrentDate(locale) {
  return new Date().toLocaleDateString(locale);
}

const irishDate = formatCurrentDate('en-IE');
const usDate = formatCurrentDate('en-US');

Functions

Functions are the verbs of your code — they represent actions. Clean, simple, and well-defined functions make your code easy to understand and maintain.

• Function names should be verbs, because functions do things.
• Functions should be small and simple enough to understand quickly. If they grow too complex, extract smaller helper functions.
• Avoid using more than three arguments. If needed, use an object to group related parameters and destructuring syntax (a very common pattern in React).
• Avoid passing boolean arguments; they often mean the function does more than one thing.
• Functions should not cause side effects — they shouldn’t modify variables or state outside their own scope. Pure functions make behavior predictable and easier to test.

// BAD
function update(u, s, notify) {
  if (notify) sendNotification(u);
  u.status = s;
  logChanges(u, s);
  calculateSomething(u, s);
  saveToDatabase(u);
}

// - Function name is vague
// - Too many responsibilities
// - Boolean argument alters behavior
// - Modifies external state (side effects)
// - Too many arguments and unclear structure

// GOOD
function updateUserStatus(user, newStatus) {
  const updatedUser = setStatus(user, newStatus);

  logUserChange(updatedUser);
  saveUser(updatedUser);
  notifyUserStatus(updatedUser);
}

/* Small helper functions */
function setStatus(user, status) {
  return { ...user, status }; // pure, no side effects
}

function logUserChange(user) {
  console.log(`User ${user.name} status changed to ${user.status}`);
}

function saveUser(user) {
  database.save(user); // isolated responsibility
}

function notifyUserStatus(user) {
  // Always clear, specific action
  sendNotification(user);
}

Comments

Comments should clarify intent, not describe what the code is doing. Code that explains itself through naming and structure is always better than one that needs constant explanation.

• Avoid redundant comments that repeat what the code already states.
• Use variable and function names to explain logic instead of comments.
• Avoid detailed documentation (like JSDoc) unless you’re writing public APIs.
• Don’t describe or refer to code that exists elsewhere — if that code changes, the comment becomes outdated.
• Keep lines short, both for code and comments.
• Write comments only when they truly add value — for instance, when explaining complex regex patterns or specific design decisions.

Testing

Testing ensures that your code behaves as expected and that improvements or refactors don’t break existing functionality.

• Writing tests guarantees reliability and reduces the risk of regressions.
• Don’t let fear of breaking something stop you from improving code — small refactors supported by tests keep systems healthy.
• Developers are responsible for code quality. QA should not be expected to find issues that proper testing would have caught.
• Use Test-Driven Development (TDD): write a failing test first, then implement code to make it pass, and finally refactor.
• Keep tests simple and focused, covering one scenario per test.

Code Review

Code reviews help maintain quality and consistency across a team’s codebase. They are opportunities to learn, improve, and refine.

• Code reviews should take almost as much time as writing the code itself.
• Focus reviews on clarity, naming, maintainability, and adherence to standards.
• Encourage continuous improvement — every review should leave the system cleaner and easier to maintain.

Conclusion

Clean code is a mindset and a responsibility. Clear naming, small functions, meaningful comments, thorough testing, and careful reviews make code easier to understand, maintain, and extend. Start small — refactor a function, improve a name, or write a test — and over time, these habits lead to cleaner, safer, and more professional code that benefits everyone. 😊