Throws Lints

Custom lint rules that enforce proper exception documentation through @throws annotations in your Dart code. This package helps maintain consistent exception handling documentation and makes it easier to identify which functions can throw exceptions.

Features

This package provides three complementary lint rules:

1. missing_throws_annotation - Ensures functions that throw exceptions directly are annotated with @throws
2. throwing_function_calls_require_throws - Ensures functions calling other @throws functions are also annotated
3. unnecessary_throws_annotation - Prevents using @throws on functions that don't actually throw

Additionally, the package exports the @throws annotation that you can use in your code.

Why Use This Package?

• Better Documentation: Clearly identify which functions can throw exceptions
• Safer Code: Know when you need to handle exceptions when calling functions
• Consistent Codebase: Enforce exception documentation standards across your team
• Catch Mistakes: Prevent forgetting to annotate throwing functions or using incorrect annotations

Installation

Enable the lints in your analysis_options.yaml:

plugins:
  throws_lints: ^1.0.0

Optional

Add throws_lints to your pubspec.yaml if you want to use @throws annotation directly from the package:

dependencies:
  throws_lints: ^1.0.0

Usage

Import the Annotation

import 'package:throws_lints/throws_lints.dart';

Rule 1: missing_throws_annotation

Functions that throw exceptions directly must have the @throws annotation.

// ❌ BAD - Missing @throws annotation
void riskyOperation() {
  throw Exception('Something went wrong');
}

// ✅ GOOD - Properly annotated
@throws
void riskyOperation() {
  throw Exception('Something went wrong');
}

// Also applies to rethrow
@throws
void handleError() {
  try {
    riskyOperation();
  } catch (e) {
    rethrow; // Must have @throws
  }
}

Rule 2: throwing_function_calls_require_throws

Functions that call other @throws functions must also have the annotation (unless they catch the exception).

@throws
void databaseOperation() {
  throw Exception('DB error');
}

// ❌ BAD - Calls throwing function without annotation
void saveData() {
  databaseOperation(); // Can throw!
}

// ✅ GOOD - Has @throws annotation
@throws
void saveData() {
  databaseOperation();
}

// ✅ GOOD - Catches the exception, no annotation needed
void saveDataSafely() {
  try {
    databaseOperation();
  } catch (e) {
    print('Save failed: $e');
  }
}

Rule 3: unnecessary_throws_annotation

Don't use @throws on functions that don't actually throw.

// ❌ BAD - Has @throws but doesn't throw
@throws
void safeFunction() {
  print('This is safe');
}

// ✅ GOOD - No annotation for safe functions
void safeFunction() {
  print('This is safe');
}

// ❌ BAD - All exceptions are caught internally
@throws
void allCaught() {
  try {
    throw Exception('Caught');
  } catch (e) {
    print('Handled: $e');
  }
}

Try-Catch Handling

The lints are smart about try-catch blocks:

@throws
void throwingFunction() {
  throw Exception('Error');
}

// ✅ No annotation needed - exception is caught
void safelyCalls() {
  try {
    throwingFunction();
  } catch (e) {
    print('Caught: $e');
  }
}

// ❌ Needs @throws - exception in finally can propagate
void finallyThrows() {
  try {
    print('Safe');
  } finally {
    throwingFunction(); // Not caught!
  }
}

Additional Information

For more examples, see the example directory.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

This package is licensed under the MIT License.