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.

v0.4.10 2024-08-04 18:04 UTC

Requires

• composer-plugin-api: *
• composer/xdebug-handler: ^3.0
• nikic/php-parser: ^4.18
• phpdocumentor/reflection-docblock: ^5.4
• savinmikhail/primitive_wrappers: ^1.2
• symfony/console: ^5.4

Requires (Dev)

• composer/composer: ^2.7
• dg/bypass-finals: ^1.8
• mikey179/vfsstream: ^1.6
• mockery/mockery: ^1.6
• phpmd/phpmd: ^2.15
• phpro/grumphp: ^1.13
• phpstan/phpstan: ^1.11
• phpunit/phpunit: ^9.6
• rector/rector: ^1.2
• squizlabs/php_codesniffer: ^3.10
• symfony/var-dumper: ^5.4

MIT

• Savin Mikhail

• comment
• static analysis
• density

README

Comments Density Analyzer

A tool to analyze the comment density and quality in PHP source code files, helping to maintain and improve code documentation quality.

Features

• Multiple Comment Types: Supports identification and analysis of several comment types including regular, docblocks, TODOs, FIXMEs, and license information.
• Missing Documentation Detection: Identifies missing docblocks, @throws tags, and generics that improve type safety and code documentation.
• Detailed Reporting: Quickly find code spots where changes might be necessary.
• Quality Check: Set up a configuration file, and if thresholds aren't met, the exit code will be returned with the report.
• Configurable Reports: Get results in either console or HTML file.
• Pre-commit hook: Validate only the files that are about to be committed.
• Baseline: Filter collected comments against a baseline to ignore old technical debt and focus on new issues.

Output Example

Installation

To install Comment Density Analyzer, run the following command in your terminal:

composer require --dev savinmikhail/comments-density

Usage

Analyze the comment density in your PHP files with:

php vendor/bin/comments_density analyze:comments

Generate baseline with:

php vendor/bin/comments_density generate:baseline

Configuration

On installation, you can allow plugin to create its configuration file. Customize your analysis by editing a comments_density.php configuration file:

<?php

return [
    'directories' => [
        'src', // Directories to be scanned for comments
    ],
    'exclude' => [
        'src/DTO', // Directories to be ignored during scanning
    ],
    'thresholds' => [
        // Limit occurrences of each comment type
        'docBlock' => 90, 
        'regular' => 5,
        'todo' => 5,
        'fixme' => 5,
        'missingDocBlock' => 10,
        // Additional metrics thresholds
        'Com/LoC' => 0.1, // Comments per Lines of Code
        'CDS' => 0.1, // Comment Density Score
    ],
    'only' => [
        'missingDocblock', // Only this type will be analyzed; set to empty array for full statistics
    ],
    'output' => [
        'type' => 'console', // Supported values: 'console', 'html'
        'file' => 'output.html', // File path for HTML output (only used if type is 'html')
    ],
    'missingDocblock' => [
        'class' => true, // Check for missing docblocks in classes
        'interface' => true, // Check for missing docblocks in interfaces
        'trait' => true, // Check for missing docblocks in traits
        'enum' => true, // Check for missing docblocks in enums
        'property' => true, // Check for missing docblocks in properties
        'constant' => true, // Check for missing docblocks in constants
        'function' => true, // Check for missing docblocks in functions
        'requireForAllMethods' => true, // If false, only methods where @throws tag or generic can be applied will be checked
    ],
    'use_baseline' => true, // Filter collected comments against the baseline stored in comments_density.sqlite
];

Acknowledgments

This project was inspired by Yegor Bugayenko. See opensource ideas.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This library is released under the MIT license.