naming-conventions

Naming Conventions

Consistent, role-carrying names make code searchable and self-explaining, and the suffix on a type declares which layer it lives in — so a reviewer, a grep, and a banned-import gate can all read the layer off the name alone. This skill is the how; the normative what is Effective Dart. Never invent a house style that contradicts the language's own.

Non-negotiable rules

1. Types are UpperCamelCase. Classes, enums, mixins, extensions, typedefs, type parameters: TaskScreen, OrderStatus, Predicate<T>. Consistent shape makes types visually distinct from values.
2. Members, variables, functions, and parameters are lowerCamelCase. dueDate, loadTasks(), itemCount. It is the language default; deviating costs readers a double-take.
3. Constants are lowerCamelCase, never SCREAMING_CAPS. const maxItemsPerPage = 50; — not const MAX_ITEMS = 50. Dart dropped the C convention; the analyzer expects constant_identifier_names.
4. Files, folders, libraries, and import prefixes are lowercase_with_underscores. task_detail_screen.dart, features/task_detail/, import 'package:app_core/app_core.dart';. Cross-platform filesystems and pub demand it.
5. File name = its primary declaration, snake_cased, one primary public type per file. TaskNotifier lives in task_notifier.dart. No utils.dart/helpers.dart/models.dart grab-bags and no utils//common//helpers//misc/ junk-drawer folders — a reader who greps a symbol must land in the file that owns it. core/ is the sanctioned pure-foundation layer (value objects, Result/Failure, the Clock seam, pure calculators), not a junk-drawer — see project-structure-and-packages, which owns the layout.
6. Acronyms longer than two letters are cased like a word. Json, Http, Url, Api → JsonOrder, HttpClient, fromJson, imageUrl — not JSONOrder, HTTPClient. Two-letter caps-in-English acronyms may stay caps as types (ID, UI). Mixed-case acronyms are unsearchable and inconsistent.
7. A leading underscore means library-private — use it only when you mean private. Never prefix a public symbol with _ to "namespace" it; that makes it unusable from another file. Public (no _) is a documented contract — see dartdoc-conventions.
8. No Hungarian / type-encoding in names. Not strName, iCount, lstItems, userMap, nameString, itemsList. The type system already knows the type; write name, usersById, items.
9. Full dictionary words; units and semantics live in the name. maxItemsPerPage, retryDelaySeconds, orderTotalMinorUnits — never bare max, delay, total. Abbreviations (opt, qty, amt) are confined to the inside of one short pure function with a comment mapping them. A name that omits its unit invites a unit bug.
10. Booleans read as assertions. isLoading, hasError, canSubmit, shouldRetry — not loading, error, retry. Boolean getters and methods start is/has/can/should so a condition reads like prose.
11. No get-prefixed accessors. Expose dueTasks, not getDueTasks(). Dart has real getters. Functions are verb phrases (loadTasks(), scheduleReminder()); non-boolean getters are noun phrases (itemCount, nextDueDate).
12. Imports grouped and sorted: dart: first, then package:, then relative — each group alphabetized, exports in their own section after imports. Let dart format plus the directives_ordering lint enforce it; never hand-fight the formatter.