|
| 1 | +# Flutter Style Guide |
| 2 | + |
| 3 | +This style guide outlines the coding conventions for contributions to the |
| 4 | +flutter/flutter repository. It is based on the more comprehensive official |
| 5 | +[style guide for the Flutter repository](https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md). |
| 6 | + |
| 7 | +## Best Practices |
| 8 | +- Code should follow the guidance and principles described in |
| 9 | + [the Flutter contribution guide](https://github.com/flutter/flutter/blob/main/CONTRIBUTING.md). |
| 10 | +- Code should be tested and follow the guidance described in the [writing effective tests guide](https://github.com/flutter/flutter/blob/main/docs/contributing/testing/Writing-Effective-Tests.md) and the [running and writing tests guide](https://github.com/flutter/flutter/blob/main/docs/contributing/testing/Running-and-writing-tests.md). |
| 11 | +- Changes to the [engine/ directory](https://github.com/flutter/flutter/tree/main/engine) should additionally have appropriate tests as described in [the engine test guidance](https://github.com/flutter/flutter/blob/main/engine/src/flutter/docs/testing/Testing-the-engine.md). |
| 12 | +- PR descriptions should include the Pre-launch Checklist from |
| 13 | + [the PR template](https://github.com/flutter/flutter/blob/main/.github/PULL_REQUEST_TEMPLATE.md), |
| 14 | + with all of the steps completed. |
| 15 | + |
| 16 | +## General Philosophy |
| 17 | + |
| 18 | +- **Optimize for readability**: Code is read more often than it is written. |
| 19 | +- **Avoid duplicating state**: Keep only one source of truth. |
| 20 | +- Write what you need and no more, but when you write it, do it right. |
| 21 | +- **Error messages should be useful**: Every error message is an opportunity to make someone love our product. |
| 22 | + |
| 23 | +## Dart Formatting |
| 24 | + |
| 25 | +- All Dart code is formatted using `dart format`. This is enforced by CI. |
| 26 | +- Constructors come first in a class definition, with the default constructor preceding named constructors. |
| 27 | +- Other class members should be ordered logically (e.g., by lifecycle, or grouping related fields and methods). |
| 28 | + |
| 29 | +## Miscellaneous Languages |
| 30 | + |
| 31 | +- Python code is formatted using `yapf`, linted with `pylint`, and should follow the [Google Python Style Guide](https://google.github.io/styleguide/pyguide.html). |
| 32 | +- C++ code is formatted using `clang-format`, linted with `clang-tidy`, and should follow the [Google C++ Style Guide](https://google.github.io/styleguide/cppguide.html). |
| 33 | +- Shaders are formatted using `clang-format`. |
| 34 | +- Kotlin code is formatted using `ktformat`, linted with `ktlint`, and should follow the [Android Kotlin Style Guide](https://developer.android.com/kotlin/style-guide). |
| 35 | +- Java code is formatted using `google-java-format` and should follow the [Google Java Style Guide](https://google.github.io/styleguide/javaguide.html). |
| 36 | +- Objective-C is formatted using `clang-format`, linted with `clang-tidy`, and should follow the [Google Objective-C Style Guide](https://google.github.io/styleguide/objcguide.html). |
| 37 | +- Swift is formatted and linted using `swift-format` and should follow the [Google Swift Style Guide](https://google.github.io/swift). |
| 38 | +- GN code is formatted using `gn format` and should follow the [GN Style Guide](https://gn.googlesource.com/gn/+/main/docs/style_guide.md). |
| 39 | + |
| 40 | +## Documentation |
| 41 | + |
| 42 | +- All public members should have documentation. |
| 43 | +- **Answer your own questions**: If you have a question, find the answer, and then document it where you first looked. |
| 44 | +- **Avoid useless documentation**: If the documentation just repeats the member's name, it's useless. Explain the *why* and the *how*. |
| 45 | +- **Introduce terms**: Don't assume the reader knows everything. Link to definitions. |
| 46 | +- **Provide sample code**: Use `{@tool dartpad}` for runnable examples. |
| 47 | +- **Provide illustrations or screenshots** for widgets. |
| 48 | +- Use `///` for public-quality documentation, even on private members. |
| 49 | + |
| 50 | +## Further Reading |
| 51 | + |
| 52 | +For more detailed guidance, refer to the following documents: |
| 53 | + |
| 54 | +- [Style guide for the Flutter repository](https://github.com/flutter/flutter/blob/main/docs/contributing/Style-guide-for-Flutter-repo.md) |
| 55 | +- [Effective Dart: Style](https://dart.dev/effective-dart/style) |
| 56 | +- [Tree Hygiene](https://github.com/flutter/flutter/blob/main/docs/contributing/Tree-hygiene.md) |
| 57 | +- [The Flutter contribution guide](https://github.com/flutter/flutter/blob/main/CONTRIBUTING.md) |
| 58 | +- [Writing effective tests guide](https://github.com/flutter/flutter/blob/main/docs/contributing/testing/Writing-Effective-Tests.md) |
| 59 | +- [Running and writing tests guide](https://github.com/flutter/flutter/blob/main/docs/contributing/testing/Running-and-writing-tests.md) |
| 60 | +- [Engine testing guide](https://github.com/flutter/flutter/blob/main/engine/src/flutter/docs/testing/Testing-the-engine.md) |
0 commit comments