savinmikhail / comments-density
CommentDensityAnalyzer is a tool designed to analyze the comment density and quality in source code files in php. It helps maintain and improve the quality of code documentation by evaluating different types of comments and providing insights into their effectiveness and appropriateness.
Installs: 220
Dependents: 1
Suggesters: 0
Security: 0
Stars: 40
Watchers: 2
Forks: 0
Open Issues: 0
Type:composer-plugin
Requires
- php: >=8.2
- composer-plugin-api: ^2.0
- ext-tokenizer: *
- composer/composer: ^2.8
- composer/xdebug-handler: ^3.0.5
- nikic/php-parser: ^5.1
- savinmikhail/primitive_wrappers: ^1.2
- symfony/cache: ^7.2
- symfony/cache-contracts: ^3.5
- symfony/console: ^6.4.10
Requires (Dev)
- bamarni/composer-bin-plugin: ^1.8
- dg/bypass-finals: ^1.8
- ergebnis/composer-normalize: ^2.43
- friendsofphp/php-cs-fixer: ^3.62
- infection/infection: ^0.29.6
- mikey179/vfsstream: ^1.6.11
- mockery/mockery: ^1.6.12
- phpmd/phpmd: ^2.15
- phpstan/phpstan: ^1.11.9
- phpunit/phpunit: ^11.3
- phpyh/coding-standard: ^2.6.1
- rector/rector: ^1.2.2
- symfony/var-dumper: ^7.1.3
README
Comments Density Analyzer
The Comments Density Analyzer is a tool to help you monitor and manage comments in your codebase.
Why Use It?
- Control TODOs and FIXMEs in CI/CD: Ensure these comments are not proliferating unchecked in your codebase.
- Spot Problematic Comments: Identify regular comments explaining "shitty code" or remnants of commented-out code.
- Enforce Documentation Standards: Require docblocks for classes and methods to maintain clear, consistent documentation.
All of this is made possible with a powerful plugin system (see the documentation for examples).
Features
- Multiple Comment Types: Detect and analyze regular comments, docblocks, TODOs, FIXMEs, and license headers.
- Plugin Support: Extend functionality by creating custom plugins via a simple interface.
- Detailed Reporting: Quickly identify areas of your code that need attention.
- Thresholds and Exit Codes: Set thresholds for comment types and return an exit code when they are exceeded.
- Configurable Reports: Output results to the console or as an HTML report.
- Baseline Support: Filter out known technical debt using a baseline file and focus on new issues.
Output Example
Installation
Install Comments Density Analyzer as a development dependency via Composer:
composer require --dev savinmikhail/comments-density
Usage
Analyze the comments in your PHP files:
php vendor/bin/comments_density analyze
Generate a baseline to ignore existing technical debt:
php vendor/bin/comments_density baseline
Configuration
During installation, the tool can generate a default configuration file. Customize your analysis by editing the comments_density.php
file:
<?php declare(strict_types=1); use SavinMikhail\CommentsDensity\AnalyzeComments\Comments\FixMeComment; use SavinMikhail\CommentsDensity\AnalyzeComments\Comments\RegularComment; use SavinMikhail\CommentsDensity\AnalyzeComments\Comments\TodoComment; use SavinMikhail\CommentsDensity\AnalyzeComments\Config\DTO\Config; return new Config( directories: [ 'src', ], thresholds: [ RegularComment::NAME => 0, TodoComment::NAME => 0, FixMeComment::NAME => 0, ], );
Acknowledgments
This project was inspired by Yegor Bugayenko. See Open Source Ideas.
Contributing
Contributions are always welcome! Feel free to submit a pull request with improvements or new features.
License
This library is licensed under the MIT License.