Script Valley
Writing Clean Code: Naming, Functions & Structure
Clean Code in Real ProjectsLesson 6.2

How to conduct a clean code review that actually improves code

code review principles, asking questions vs mandating, naming feedback, function size feedback, automated vs manual review

Code Reviews That Improve Code and Morale

Code review approach comparison

A code review's job is to improve the code and grow the reviewer. Done wrong, it creates resentment and doesn't improve the code. The difference is usually tone and intent.

Ask, don't mandate:

// Bad review comment
"This function name is wrong. Fix it."

// Good review comment  
"Would 'validateEmailFormat' be clearer here?
The current name 'check' doesn't tell me
what's being checked or what format is expected."

Only flag clean code issues that weren't caught by the linter โ€” if the linter should have caught it, the fix is a linter rule, not a review comment. Focus manual review time on things tools can't check: naming accuracy, function responsibility, whether abstractions make sense, business logic correctness.

Separate style from substance in reviews. Style comments ("I'd use single quotes here") should be automated away. Substance comments ("this function now has two responsibilities") are worth the review time.

Praise explicitly, not vaguely. "Good job" is noise. "Extracting the validation into assertPositiveAmount makes the business rule immediately readable" gives the author something concrete to remember and repeat.

Agree as a team on clean code rules before reviews happen. Debating naming conventions in a PR comment thread wastes time and creates conflict. Write the standards down, put them in a CONTRIBUTING.md, and reference them in review comments when needed.

Up next

How to balance clean code with deadlines in a real team

Sign in to track progress

How to conduct a clean code review that actually improves code โ€” Clean Code in Real Projects โ€” Writing Clean Code: Naming, Functions & Structure โ€” Script Valley โ€” Script Valley