Flutter Style Guide

This style guide outlines the coding conventions for contributions to the flutter/flutter repository. It is based on the more comprehensive official style guide for the Flutter repository.

Best Practices

• Code should follow the guidance and principles described in the Flutter contribution guide.
• Code should be tested and follow the guidance described in the writing effective tests guide and the running and writing tests guide.
• Changes to the engine/ directory should additionally have appropriate tests as described in the engine test guidance.
• PR descriptions should include the Pre-launch Checklist from the PR template, with all of the steps completed.
• The most relevant guidelines should take precedence over less relevant guidelines. For Flutter code, the Flutter styleguide should be followed as the first priority, and Effective Dart: Style should only be followed when it does not conflict with the former.

Review Agent Guidelines

• Only review changes to the master branch. Other changes have already been reviewed (and are being cherrypicked).

General Philosophy

• Optimize for readability: Code is read more often than it is written.
• Avoid duplicating state: Keep only one source of truth.
• Write what you need and no more, but when you write it, do it right.
• Error messages should be useful: Every error message is an opportunity to make someone love our product.

Dart Formatting

• All Dart code is formatted using dart format. This is enforced by CI.
• Constructors come first in a class definition, with the default constructor preceding named constructors.
• Other class members should be ordered logically (e.g., by lifecycle, or grouping related fields and methods).

Miscellaneous Languages

• Python code is formatted using yapf, linted with pylint, and should follow the Google Python Style Guide.
• C++ code is formatted using clang-format, linted with clang-tidy, and should follow the Google C++ Style Guide.
• Shaders are formatted using clang-format.
• Kotlin code is formatted using ktformat, linted with ktlint, and should follow the Android Kotlin Style Guide.
• Java code is formatted using google-java-format and should follow the Google Java Style Guide.
• Objective-C is formatted using clang-format, linted with clang-tidy, and should follow the Google Objective-C Style Guide.
• Swift is formatted and linted using swift-format and should follow the Google Swift Style Guide.
• GN code is formatted using gn format and should follow the GN Style Guide.

Documentation

• All public members should have documentation.
• Answer your own questions: If you have a question, find the answer, and then document it where you first looked.
• Documentation should be useful: Explain the why and the how.
• Introduce terms: Assume the reader does not know everything. Link to definitions.
• Provide sample code: Use {@tool dartpad} for runnable examples.
  • Inline code samples are contained within {@tool dartpad} and {@end-tool}, and use the format of the following example to insert the code sample:
    • /// ** See code in examples/api/lib/widgets/sliver/sliver_list.0.dart **
    • Do not confuse this format with /// See also: sections of the documentation, which provide helpful breadcrumbs to developers.
• Provide illustrations or screenshots for widgets.
• Use /// for public-quality documentation, even on private members.

Review Agent Guidelines

When providing a summary, the review agent must adhere to the following principles:

• Be Objective: Focus on a neutral, descriptive summary of the changes. Avoid subjective value judgments like “good,” “bad,” “positive,” or “negative.” The goal is to report what the code does, not to evaluate it.
• Use Code as the Source of Truth: Base all summaries on the code diff. Do not trust or rephrase the PR description, which may be outdated or inaccurate. A summary must reflect the actual changes in the code.
• Be Concise: Generate summaries that are brief and to the point. Focus on the most significant changes, and avoid unnecessary details or verbose explanations. This ensures the feedback is easy to scan and understand.

Further Reading

For more detailed guidance, refer to the following documents:

• Style guide for the Flutter repository
• Effective Dart: Style
• Tree Hygiene
• The Flutter contribution guide
• Writing effective tests guide
• Running and writing tests guide
• Engine testing guide