Blog

What Clean Code Means: A Pull Request Review Checklist

"Clean code" is one of those phrases that sounds meaningful and falls apart the moment someone asks you to define it. Say it in a code review and it lands. Try to explain what you actually mean and it turns vague. The fix is to stop treating it as an aesthetic and start treating it as a checklist: a specific set of things you look for when you read someone's pull request.

Here is the definition I would give, and it is not a buzzword: clean code is code written for the next person who has to read it. Code is read far more often than it is written, so clean code optimizes for the reader. It is easy to read, easy to understand, and safe to change. Everything below is a lens on that one idea.

What clean code actually means

The abstract idea becomes concrete when you break it into the things you can point at.

Eight dimensions of clean code, each with a short description. Names: intention-revealing, the name says what and why. Functions: small, do one thing, few arguments, no surprises. Comments: explain why, not what, and delete the rest. No duplication: one source of truth, repeated logic is a smell. Error handling: fail clearly, never swallow an exception. One responsibility: a class has one reason to change. Tests: enough to change the code without fear. Simplicity: the simplest thing that works, no over-building.

None of these is exotic. Together they are what "clean" points at: names that explain themselves, functions small enough to hold in your head, comments that add what the code cannot say, no copy-paste, failures handled honestly, each piece with one job, tests you can lean on, and no cleverness for its own sake.

Clean code as a code review

Now the useful frame. When you review a pull request, you are really running these dimensions as questions against the diff. That is the answer to "what does clean code mean to you," made concrete.

A pull-request review checklist. Can I tell what it does from the names alone? Does each function do one thing? Do comments explain why, or just restate the code? Is there duplicated logic that should be extracted? Are failures handled, not silently swallowed? Does it match the codebase's existing conventions? Is the change tested, and are the tests readable? Is this the simplest solution, or is it over-built? Underneath all of them, the real question is whether a teammate could safely change this in six months.

Run them in order on any change and your feedback stops being "this feels messy" and becomes specific: this name hides intent, this function does three things, this comment just repeats the code, this logic is duplicated two files over. That is reviewable, and it is teachable, which is the point of a review.

What clean looks like

The highest-leverage item on that list is naming. A good name removes the need for a comment and makes the code state what it does, which is why "self-documenting" is less a slogan than a consequence of naming things well. The whole idea fits in one small before-and-after.

The same logic before and after cleaning it up. Before, harder to read: a comment saying "check if user can see reports" above an if statement with cryptic conditions, u.t equals 1 and u.a greater than 17 and not u.b, calling show of u. After, clean: an if statement reading user.CanViewReports, calling showReports of user. A good name makes the comment and the magic conditions unnecessary, and the code now reads like a sentence.

The clean version did not add anything clever. It moved the meaning out of a comment and a pile of magic conditions and into a well-named method. Now the code says what it does, and there is nothing to keep in sync.

One honest caveat

Clean code is a set of principles and judgment, not a rulebook to apply mechanically. Taken to an extreme, "small functions" becomes a maze of one-line methods, and "no comments" becomes deleting the one comment that would have saved the next person an hour. The goal is always readability and safe change, not rule-following. When a principle and that goal disagree, the goal wins. Knowing when to bend a rule is itself part of writing clean code.

The one-line version

If you only keep one sentence, keep this. Clean code is code optimized for the reader: intention-revealing names, small functions that do one thing, comments that explain why rather than what, no duplication, honest error handling, and enough tests to change it without fear. When I review a pull request, I am really asking one question, and every item on the checklist is a way of asking it: could a teammate understand and safely change this in six months?

That is what "clean code" means, said in a way you can actually defend.

If you want a developer who reviews for that standard, not just working code but code the next person can live with, that is how I work. You can get a quote, or read more on how I think about a codebase's structure in reading nopCommerce as a system.

All posts