Code Formatting & Linting

Code Formatting & Linting

Nobody likes arguing about where a bracket should go or whether to use single or double quotes. To avoid those "bikeshedding" discussions and keep our codebase looking consistent, we automate as much of this as possible.

We enforce two things:

1. Formatting: How the code looks (indentation, spacing, etc.).

2. Linting: How the code works (best practices, potential bugs, unused variables).

1. Formatting (The Look)

We use the official dart format tool. It has no configuration options, which is great because it means there's nothing to argue about. The tool is always right.

How to Format

• Option A: The Pre-Commit Hook (Recommended): If you installed our pre-commit hook (see below), you never have to think about this. It runs automatically every time you git commit.

• Option B: VS Code "Format on Save": You can set up VS Code to format your file every time you save it.

  1. Open Settings (Ctrl+, or Cmd+,).
  2. Search for "Format on Save".
  3. Check the box.
  4. Make sure your "Default Formatter" is set to Dart.

• Option C: The Manual Way: If you need to format files manually via the terminal:

# In packages/uni_app
dart format .

2. Linting (The Logic)

We use very_good_analysis. This is a strict set of rules that catches common bugs and enforces best practices.

If you see a blue or yellow squiggly line in VS Code, that's the linter talking to you.

How to Check for Issues

In VS Code: Open the "Problems" tab (Ctrl+Shift+M or Cmd+Shift+M). It will list all linting errors in your project.

• In Terminal:

# In packages/uni_app
flutter analyze

• Dealing with Linter Rules

  1. Fix it (Preferred): Most of the time, the linter is right. If it says "prefer const constructors," add a const.
  2. Ignore it (Rarely): Sometimes a rule doesn't make sense in a specific context. You can ignore a rule for a specific line using a comment:

// ignore: public_member_api_docs
void myUndocumentedFunction() { ... }

Please use this sparingly. If you ignore a rule, it's often nice to leave a comment explaining why.

3. The Pre-Commit Hook

We have a script pre-commit-hook.sh in the root of the repository.

• What it does: When you try to commit code, this script runs. It checks the files you are about to commit and:

  1. Runs dart format on them.
  2. If the formatting changed, it updates the file and adds it to the commit.

• How to install it:

# From the root of the repo
chmod +x pre-commit-hook.sh
./pre-commit-hook.sh

• Why you should use it: Our CI/CD pipeline runs a strict formatting check. If you push code that isn't formatted, the build will fail and you won't be able to merge your PR until you fix it. The hook saves you from that embarrassment.

4. Continuous Integration (CI)

Every time you push a PR, a GitHub Action (format_lint_test.yaml) wakes up and runs:

1. dart format --set-exit-if-changed . (Fails if code isn't formatted)

2. flutter analyze . (Fails if there are lint errors)

If you see a red ❌ on your PR, check the logs. 90% of the time, it's a formatting issue you can fix by running dart format . and pushing again.