Skip to main content

The Art of Flutter Code Review: A Guide for Reviewers & Authors

SR
Sabin Ranabhat
Published December 31, 2025•6 min read
The Art of Flutter Code Review: A Guide for Reviewers & Authors

Code review is the primary mechanism for maintaining long-term system health, ensuring architectural integrity, and fostering team growth. It is not just about finding bugs; it is about ensuring the codebase remains predictable, maintainable, and scalable.

📖 What is Code Review? Code review is a quality assurance process where one or more developers examine code written by a teammate before it is merged into the main codebase. Think of it as a second set of eyes that helps catch bugs, improve code quality, share knowledge across the team, and ensure everyone follows the same standards.

📚 Related Guidelines: This guide works in tandem with:


✍️ The Author's Responsibility (Prerequisites)

High-quality reviews start with high-quality Pull Requests (PRs). Before requesting a review, the author must adhere to the Submit Pull Request standards:

  • Atomic Scope: Keep PRs focused on a single purpose (aim for <400 lines). Small PRs result in better reviews and fewer bugs.
  • Visual Proof: UI changes must include screenshots or screen recordings (as per the "UI Proof" guidelines).
  • Self-Review: You are the first reviewer. Fix formatting, remove dead code, and ensure flutter analyze passes.
  • Context is King: The description must answer "What?" and "Why?", linking to relevant tickets.

🧠 Mindset & Human Factors

Effective code review requires psychological safety. We critique the code, not the coder.

GuidelineImplementation
Assume Positive IntentFrame feedback neutrally.
Distinguish preference vs. requirementUse labels: [Blocking] for critical issues, [Nit] for optional polish.
Speed MattersAim for first feedback within 24 hours. Beyond 3 back-and-forths, hop on a call.

Good vs. Bad Comment Examples

❌ Bad Comment✅ Good CommentWhy It's Better
"You forgot to handle nulls.""Could we handle the null case here?"Neutral, non-accusatory
"This is wrong.""This might cause X issue because Y. What do you think?"Explains reasoning, invites dialogue
"Don't do it this way.""[Nit] Have you considered using X instead? It might be cleaner."Labels as optional, offers alternative
"Fix this.""[Blocking] This could cause a memory leak. We need to dispose the controller."Explains severity and reason
"Why did you do this?""I'm curious about the reasoning here—could you elaborate?"Genuinely curious, not attacking

🛠️ The Technical Review Framework

Don't read line-by-line immediately. Use a multi-pass approach to catch high-level issues first.

Pass 1: Git Hygiene & Standards

Before looking at the code, check the metadata.

  • Conventional Commits: Does the PR title and commit history follow the Conventional Commits specification?
    • Format: <type>(<scope>): <description> (e.g., feat(auth): add login button).
    • Types: feat, fix, refactor, style, chore, test, perf.
  • Clean History: Are "WIP" or "fix typo" commits squashed? The history should tell a clean story.

Pass 2: Architecture & Design (High Altitude)

  • Does this solve the right problem?
  • Is this the right place? (e.g., Logic in ViewModel vs View).
  • Are boundaries respected? (No leakage of data models into UI layers).
  • If the design is flawed, stop the review and discuss high-level changes.

Pass 3: Correctness & Logic (Deep Dive)

  • Edge Cases: Nulls, empty lists, network errors, race conditions.
  • State Management: Is state mutated safely?
  • Tests: Do tests exist? Do they cover the behavior, not just lines?
  • Complexity: Is the logic hard to follow? Can it be simplified?

Pass 4: Safety & Performance

  • Security: Input validation, no hardcoded secrets, safe storage.
  • Performance: No expensive loops, unnecessary rebuilds, or memory leaks (streams/controllers disposed).

Pass 5: Polish (Readability & Style)

  • Naming: Descriptive names (userId vs id).
  • Docs: Comments added for complex logic?

🐦 Flutter & Dart Specifics

AreaChecklist
Null Safety• Avoid the force bang operator ! unless absolutely guaranteed.• Use late only when initialization is strictly guaranteed before use.
Async Safety• Check Mounted: Always use if (!context.mounted) return; after an await before using BuildContext (e.g., popping or showing snackbars).
Widget Architecture• No Logic in Build: The build() method must be pure and fast. No HTTP calls or complex filtering.• Extract Widgets: Break large build methods into smaller stateless widgets (adds const support).
Memory Leaks• Dispose: Ensure TextEditingController, AnimationController, StreamSubscription are disposed.• Global Listeners: Careful with global ChangeNotifier listeners.
Performance• Use const: Everywhere possible.• Build Scope: Use Selector or specific BlocBuilder filters to rebuild only what changed.

⚖️ Resolving Disagreements

Disagreements are healthy, but stalemates are expensive.

  1. Discuss: Discuss in comments.
  2. Escalate: If unresolved after 3 replies, move to a synchronous call/huddle.
  3. Decide:
    • If it's a matter of preference: The Author has the final tie-breaking vote (or follow the Style Guide).
    • If it's a matter of correctness/risk: The Reviewer (or Tech Lead) has the veto.
  4. Commit: Once decided, move forward without resentment.

✅ Final Checklist

1. Prerequisites & Hygiene (Blocking)

  • Standards: Title follows Conventional Commits?

  • Scope: Is the PR size manageable (<400 LOC)?

  • Context: Is "Why" explained? Visuals attached for UI?

  • Architecture: Fits existing patterns?

2. Correctness & Logic (Blocking)

  • Functionality: Meets acceptance criteria?

  • Edge Cases: Nulls, errors, empty states handled?

  • Async Safety (Flutter): context.mounted checked after await?

  • Memory: Controllers/Streams disposed?

3. Quality & Testing (Blocking)

  • Tests: Unit/Widget tests added?

  • Test Quality: Asserts behavior, not implementation?

  • Style/Lint: CI checks passed?

4. Polish (Non-Blocking / Nit)

  • Naming: Clear and descriptive?

  • Docs: Comments for complex logic?


References

Share this article:
Sabin Ranabhat

Written by Sabin Ranabhat

I'm a Senior Software Engineer specializing in full-stack development with TypeScript, React, Next.js and Node.js, with deep Flutter, iOS, and Android experience. I'm currently open to new remote roles and challenges. If you need a specialist to lead your full-stack development, let's talk.

Related Posts