Comment Lint
A comment style linting and auto-fixing tool for Dart and Flutter projects that enforces consistent comment formatting across your codebase.
The package is published on pub.flutter-io.cn.
Features
- π§ Enforces consistent comment style across your Dart/Flutter project
- π Intelligent comment rules:
- Comments should end with periods (for readability)
- Uppercase headers (e.g.,
// MOVIE METHODS
) should not have periods - No periods after colons or commas in comments
- Smart handling of multi-line continuation comments
- π Proper spacing - Ensures blank lines between comments and code
- π― Smart ignoring - Skips generated files, license headers, TODOs, and URLs
- π Auto-fixing - Can automatically fix violations or just report them
- β CI/CD ready - Exit codes for automated pipelines
- π Cross-platform - Works on Windows, macOS, and Linux
Installation
Install as a global executable:
dart pub global activate comment_lint
Or add to your pubspec.yaml
:
dev_dependencies:
comment_lint: ^0.1.0
π― Quick Start
Check comment style (CI/CD mode):
# Check lib directory
dart run comment_lint --check
# Check specific directories
dart run comment_lint --check lib test
# For CI/CD (returns exit code 1 if issues found)
dart run comment_lint --set-exit-if-changed lib
Fix comment style:
# Fix lib directory
dart run comment_lint
# Fix specific directories
dart run comment_lint lib test
# Preview changes without applying them
dart run comment_lint --dry-run
Global installation usage:
# After: dart pub global activate comment_lint
comment_lint --check lib
comment_lint lib # to fix
Comment Style Rules
β Good Examples:
// This is a proper comment with a period.
// MOVIE METHODS (uppercase headers don't need periods)
// This is a list item:
// - First item
// - Second item
// Multi-line comments are handled intelligently,
// where continuation lines don't need periods.
/// Documentation comments work too.
β Bad Examples:
// Missing period
// UPPERCASE HEADER. (should not have period)
// Wrong after colon:.
// No blank line before code
void someFunction() {}
CLI Options
Option | Description |
---|---|
--check , -c |
Check comment style without fixing |
--set-exit-if-changed |
Return exit code 1 if changes needed (for CI/CD) |
--dry-run |
Preview what would be changed without applying |
--verbose , -v |
Show detailed output |
--help , -h |
Show help information |
CI/CD Integration
Add to your GitHub Actions workflow:
- name: Check comment style
run: dart run comment_lint --set-exit-if-changed
Or in your Makefile
:
lint-comments:
dart run comment_lint --set-exit-if-changed lib test
fix-comments:
dart run comment_lint lib test
How It Works
The tool uses a hybrid approach:
- Dart CLI for cross-platform compatibility and argument parsing
- Bash scripts for the core text processing logic (fast and reliable)
- Smart detection for various comment patterns and edge cases
Ignored Patterns
The linter automatically ignores:
- Generated files (
*.g.dart
) - License headers and copyright notices
- Analyzer ignore directives (
// ignore:
) - TODOs, FIXMEs, and NOTEs
- URLs and hyperlinks
- Empty comments
Multi-line Comment Handling
The tool intelligently detects continuation comments:
// This is a multi-line comment that explains something complex,
// and this line doesn't need a period because it continues.
// But this final line does need a period.
void someCode() {} // Blank line added automatically
Examples
Basic Usage:
# Check comment style in default lib directory
dart run comment_lint --check
# Fix comment style in lib and test directories
dart run comment_lint lib test
# Preview changes without applying
dart run comment_lint --dry-run lib
Advanced Usage:
# Verbose output for debugging
dart run comment_lint --verbose --check lib
# Use in CI/CD pipeline
dart run comment_lint --set-exit-if-changed lib test
if [ $? -ne 0 ]; then
echo "Comment style issues found!"
exit 1
fi
Development
Running Tests:
cd comment_lint
dart test
Contributing:
- Fork the repository
- Create a feature branch
- Add tests for new functionality
- Ensure all tests pass
- Submit a pull request
License
This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.
Related Projects
- import_order_lint - Import ordering linter
- dart format - Official Dart formatter
Changelog
See CHANGELOG.md for version history and changes.