Convention Check

Convention Check (Flutter/Dart — Code)

Audits code changes against the team's six Dart coding conventions and produces a prioritized, actionable report.

For commit message checks, use /commit-check instead.

How to get the diff

Do not ask the user to paste a diff, and do not ask them to select files. Retrieve and analyze everything automatically:

Step 1 — Identify the base branch

• If the user provided a base branch or PR number, use it.
• Otherwise ask: "What is the base branch? (e.g., main, develop)"

Step 2 — Get the full diff

# List changed files (for display only)
git diff $(git merge-base HEAD <base-branch>) --name-only

# Full diff for analysis
git diff $(git merge-base HEAD <base-branch>)

Analyze all changed files. Skip generated files automatically (see below) — do not ask the user to choose.

Only flag lines the diff adds or modifies (lines starting with +). Context lines and removed lines are out of scope.

Files to ignore (auto-generated)

• *.g.dart, *.freezed.dart, *.mocks.dart, *.gen.dart, *.config.dart
• Anything under build/, .dart_tool/, ios/Pods/, android/.gradle/, .flutter-plugins*
• pubspec.lock

If the diff is dominated by generated files, mention this and focus on the hand-written changes.

The six rules

Evaluate all six rules. Collect all violations before writing the report.

Rule 1 — Naming conventions (camelCase / PascalCase / snake_case)

Key checks:

• State classes: _MyWidgetState for MyWidget extends StatefulWidget — flag missing leading underscore.
• Constants: lowerCamelCase (not SCREAMING_SNAKE_CASE).
• Acronyms: HttpClient, parseJsonResponse, userId — flag HTTPClient, parseJSONResponse, userID.
• File names: a file named LoginScreen.dart is wrong even if the class inside is correct → login_screen.dart.
• Persistence layer: SQLite/Drift/Isar/Hive table/collection names must be snake_case.
• Variable/parameter names must be nouns or adjectives — never start with a verb:
  • final fetchUser = ... → final user; final calculateTotal = ... → final total
  • Boolean predicates starting with is, has, can, should are fine: isLoading, hasError, canSubmit
  • Methods and functions may (and should) start with verbs: fetchUser(), calculateTotal()

Rule 2 — Remove unnecessary commented-out code

Flag: commented-out executable code that serves no purpose.

• // final oldResult = legacyCompute(x);
• Large /* … widget tree … */ blocks left after a refactor.

Don't flag:

• // TODO(name): explanation
• // reason why this code exists
• /// dartdoc comments
• License headers
• // ignore: <lint_rule> directives

Heuristic: removing the comment markers produces syntactically valid Dart of the same shape → it's dead code.

Rule 3 — Use meaningful variable and function names

Flag:

• Single-letter names outside tight scope — loop i, short callback e, coordinates x/y are fine. final d = await getUser() at function scope is not.
• Generic placeholders: data, info, tmp, temp, foo, bar, obj, val, result — when a more specific name is obvious from context.
• Type-in-name: userList → users; userMap → usersById; stringName → the actual concept.
• Generic widget names: Widget1, MyButton, CustomContainer → PrimaryButton, CartItemTile.
• Noise callbacks: onTap1, handler2 → name by what they do (onLoginPressed, handleRefresh).

Always propose a specific rename, not just "rename this."

Rule 4 — No abbreviations (except widely-known ones: ID, URL, etc.)

Allowed — do not flag:

ID, URL, URI, HTTP, HTTPS, API, UI, UX, DB, SQL, HTML, CSS, JS, TS,
JSON, XML, YAML, CSV, PDF, CPU, GPU, RAM, IO, OS, UUID, ISO, UTC, TZ,
TLS, SSL, DNS, IP, TCP, UDP, REST, gRPC, CLI, SDK, CDN, JWT, OAuth,
MD5, SHA, CORS, env, iOS, MVVM, MVC, DI, IoC, ORM, BLoC, SVG,
PNG, JPG, GIF, RGB, RGBA, DP, SP, PX, FPS, APK, AAB, IPA, ADB, FCM,
APNs, ref (Riverpod Ref/WidgetRef only)

Flag everything else:

Borderline → use 検討 (Consider):

• ctx — very common for BuildContext but Effective Dart recommends context
• auth, config — real words in common use
• bloc — fine as a class suffix (LoginBloc); flag as a standalone variable

Rule 5 — Document public APIs with clear comments

Scope

Format: Use /// (not //, not /** */). Reference symbols with [SymbolName].

Step 1 — Always skip (never flag):

• Private members (leading _)
• Test files (test/**, *_test.dart, integration_test/**)
• Widget state classes (_FooState) and *State plain data holders (e.g., LoginState, SettingState)
• Trivial overrides: build, dispose, toString, ==, hashCode, createState
• Generated files (*.g.dart, *.freezed.dart, etc.)

Step 2 — Skip if method is obviously self-explanatory (all must be true):

• Body is ≤ 3 lines, no async/await
• No dependency calls (_repository, _service, _dio, _storage, http, SharedPreferences, etc.)
• No try/catch, no throw
• Body is a simple field access or single delegation — regardless of return type

void clear() => _cache.clear();      // obvious — skip
bool get isEmpty => _items.isEmpty;  // obvious — skip
User get currentUser => _user;       // obvious — skip

If any signal is missing → not obvious → proceed to Step 3.

Step 3 — Flag:

Analyzing logic changes in existing docs (applies to shared zone only):

When the diff modifies a public method that already has ///, compare the existing doc against the new code:

• New exception added → doc must list it under a /// Throws line
• Parameter added, removed, or semantically changed → doc must reflect the new signature
• Return contract changed (e.g., now returns null on a new condition) → doc must describe the new contract
• Internal restructuring with no behavioral change → no flag needed

Example:

// 検討 — restates the name, no useful info
/// Fetches the user.
Future<User> fetchUser(String id) async { /* ... */ }

// Good — behavior, edge cases, throws
/// Fetches a [User] by [id] from the remote API.
/// Throws [NotFoundException] if the user does not exist.
/// Throws [NetworkException] on connectivity failure.
Future<User> fetchUser(String id) async { /* ... */ }

// Good — Riverpod provider in lib/providers/
/// Provides the current authentication state.
/// Automatically invalidated when the session token changes.
final authStateProvider = StateNotifierProvider<AuthController, AuthState>(
  (ref) => AuthController(ref),
);

Rule 6 — No missing newline at end of file (for new or modified endings)

When to flag: only when the current PR's diff is responsible for the missing newline — that is, when a diff hunk ends with the git marker:

\ No newline at end of file

This naturally covers two cases:

• A newly created file (all lines are +) that has no trailing newline.
• Existing code modified at the end of a class/file — the last line of the file appears in the diff and has no trailing newline.

Do NOT flag a file where the author only changed the middle — if the last line is not part of any + hunk in the diff, the marker will not appear and it is out of scope for this PR.

Severity: 要修正 — causes spurious diff noise in future changes and breaks POSIX tools.

Fix: add one newline character at the very end of the file.

Severity

Two levels — consistent with pre-pr-review:

When in doubt, prefer 検討 over 要修正.

Output format

# Convention audit

**Scope:** <e.g. "5 Dart files (2 generated files skipped)">
**Base branch:** <branch>
**Result:** N 要修正 · N 検討

## 要修正 (Must fix)

- **`lib/services/AuthService.dart`** — Rule 1 (file naming). Rename to `auth_service.dart`.
- **`lib/services/auth_service.dart:12`** — Rule 1 (class naming). `class authService` → `class AuthService`.

## 検討 (Consider)

- **`lib/screens/login/login_controller.dart:8`** — Rule 3 (meaningful names). `final data = await fetchProfile()` → `userProfile`.

## ✓ Clean rules

<Rules with no violations.>

If there are zero violations, say so plainly.

What to avoid

• Don't flag unchanged context lines — only + lines in the diff.
• Don't add rules the team didn't ask for — no dart format, no prefer_const_constructors, no import-order preferences.
• Don't review generated files.
• Don't be dogmatic — use 検討 for auth, config, ctx, ref.
• Don't restate the full rule text — a short reference like "Rule 4 (abbreviations)" is enough.
• Don't reformat code — show short snippets to locate the issue only.