When syntax noise hides real design problems
TL;DR: When you focus code reviews on syntax, you miss architecture, security, design and intent.
Problems
- Syntax fixation
- Design blindness
- Missed risks
- Bad feedback
- Useless discussions
- Reviewer fatigue
- False quality
- Shallow feedback
- Syntax Police
- Low team morale
Solutions
- Leave the boring work to the IA
- Automate style checks
- Review architecture first
- Discuss intent early with technical analysis and control points
- Enforce review roles
- Raise abstraction level
Refactorings ⚙️
https://maximilianocontieri.com/refactoring-032-apply-consistent-style-rules
https://maximilianocontieri.com/refactoring-016-build-with-the-essence
Context
When you review code, you choose where to spend your valuable human attention.
When you spend that attention on commas, naming trivia, or formatting, you ignore the parts that matter.
This smell appears when teams confuse cleanliness with correctness. Syntax looks clean. Architecture rots.
Sample Code
Wrong ❌
<?php
class UserRepository {
public function find($id){
$conn = mysqli_connect(
"localhost", // Pull Request comment - Bad indentation
"root",
"password123",
"app"
);
$query = "Select * FROM users WHERE id = $id";
// Pull Request comment - SELECT should be uppercase
return mysqli_query($conn, $query);
}
}
Right
<?php
final class UserRepository {
private Database $database;
public function __construct(Database $database) {
$this->database = $database;
}
public function find(UserId $id): User {
return $this->database->fetchUser($id);
}
}
// You removed credentials, SQL, and infrastructure noise.
// Now reviewers can discuss design and behavior.
Detection
[X] Manual
You can detect this smell by examining pull request comments.
When you see multiple comments about formatting, indentation, trailing commas, or variable naming conventions, you lack proper automation.
Check your continuos integration pipeline configuration. If you don't enforce linting and formatting before human review, you force reviewers to catch these issues manually.
Review your code review metrics. If you spend more time discussing style than architecture, you have this smell.
Automated tools like SonarQube, ESLint, and Prettier can identify when you don't enforce rules automatically.
Level
[x] Intermediate
Why the Bijection Is Important ️
Code review represents the quality assurance process in the MAPPER.
When you break the bijection by having humans perform mechanical checks instead of judgment-based evaluation, you mismodel the review process.
You no longer validate whether the concepts, rules, and constraints match the domain.
You only validate formatting.
That gap creates systems that look clean and behave wrong.
The broken bijection manifests as reviewer fatigue and missed bugs. You restore proper mapping by separating mechanical verification (automated) from architectural review (human).
AI Generation
AI generators often create this smell.
They produce syntactically correct code with weak boundaries and unclear intent.
AI Detection
AI can reduce this smell when you instruct it to focus on architecture, invariants, and risks instead of formatting.
Give them clear prompts and describe the role and skills of the reviewer.
Try Them!
Remember: AI Assistants make lots of mistakes
Suggested Prompt: Find real problems in the code beyond nitpicking, review this code focusing on architecture, responsibilities, security risks, and domain alignment. Ignore formatting and style.
Conclusion
Code reviews should improve systems, not satisfy linters.
When you automate syntax, you free humans to think.
That shift turns reviews into real design conversations.
Relations ❤️
https://coderlegion.com/8216/code-smell-06-too-clever-programmer
https://maximilianocontieri.com/code-smell-48-code-without-standards
https://coderlegion.com/8106/code-smell-05-comment-abusers
https://maximilianocontieri.com/code-smell-173-broken-windows
https://maximilianocontieri.com/code-smell-236-unwrapped-lines
Disclaimer
Code Smells are my opinion.
Credits
Photo by Portuguese Gravity on Unsplash
Design is about intent, not syntax.
Grady Booch
https://maximilianocontieri.com/software-engineering-great-quotes
This article is part of the CodeSmell Series.
https://maximilianocontieri.com/how-to-find-the-stinky-parts-of-your-code