Why should a Flutter team never judge a janky screen's performance in debug mode, and what should they do instead?

## The scenario A teammate says a screen is janky. They open it on the Android emulator with `flutter run`, scroll, see stutter and frame times well above budget, and start rewriting widgets. Before anyone optimizes anything, the right question is: **what build mode, on what device?** ## Why debug-mode numbers mislead Debug mode is built for fast edit cycles, not speed. The Flutter docs say plainly that performance can be janky in debug mode and that performance should be measured in profile mode on an actual device. The reasons: - **JIT instead of AOT.** Debug builds run code in the Dart VM with just-in-time compilation to support hot reload. Profile and release builds ship ahead-of-time compiled machine code. - **Assertions everywhere.** The framework is full of `assert` checks that validate layout, painting and state. They run on every frame in debug and are compiled out in profile and release. - **Debug-only work.** Code gated by `kDebugMode` or inside asserts, service extensions and debugger hooks all add overhead. - **The wrong device.** Emulators and simulators do not behave like a phone's CPU and GPU. The iOS Simulator only runs debug builds at all, and the docs describe emulators and simulators as unrepresentative of real performance. The effect is not a constant slowdown you can divide out: different code paths slow down by different amounts, so debug numbers can point at the wrong culprit. ## What to do instead 1. **Use a physical device**, ideally a lower-end one that matches your users. 2. **Build in profile mode**: `flutter run --profile`. It compiles ahead of time like release but keeps tracing and lets DevTools connect. 3. **Reproduce the same interaction** and look at the results with the performance tools (reading frame charts is a separate skill). 4. **Only then optimize**, and re-measure in profile mode after each change. ## What profile mode still gives you | Available in profile | Not available in profile | |---|---| | Tracing and timeline events | Hot reload and hot restart | | DevTools connection | Assertions | | Performance overlay service extension | Debug painting and other debug-only extensions | | Widget build profiling extensions | Source-level debugging | That split is deliberate: profile keeps what you need to **observe** performance and drops what **distorts** it. ## Traps inside the measurement - **Code that behaves differently by mode.** The `kReleaseMode` documentation warns that gating logic on `kReleaseMode` introduces differences between release and profile builds, making performance testing less representative. Gate debug-only work with `kDebugMode` or `assert` instead, so profile and release run the same code. - **The web.** Profile builds of a Flutter web app use `dart2js` without minification, and DevTools cannot connect to them; use the browser's own performance tools. - **First runs.** Measure a few repetitions, not just the first scroll after launch. ## How to say it in an interview Name the rule, give the reasons, and describe the fix: "Debug mode is JIT-compiled and full of assertions, so its timings are not representative; I would reproduce the jank in profile mode on a real device, confirm it there, and only then optimize." Pointing out that the emulator itself is part of the problem shows production experience. ## A checklist before anyone reports a performance problem - The build was made with `--profile`, not the default debug mode. - It ran on a physical device representative of real users, not an emulator or the iOS Simulator. - The interaction was repeated several times, not measured once right after launch. - No debug-only work, such as verbose logging behind `!kReleaseMode`, runs in the profile build. - The same steps are written down, so the measurement can be repeated after the fix in the same mode on the same device.