README

注释密度分析器

一个用于分析 PHP 源代码文件中注释密度和质量的工具，有助于维护和提升代码文档质量。

功能

• 多种注释类型：支持识别和分析多种注释类型，包括常规注释、文档块、TODO、FIXME 和许可证信息。
• 缺失文档检测：识别缺失的文档块、@throws 标签和泛型，以提升类型安全和代码文档。
• 详细报告：快速找到可能需要修改的代码位置。
• 质量检查：设置配置文件，如果阈值未达标，则返回带有报告的退出代码。
• 可配置报告：以控制台或 HTML 文件的形式获取结果。
• 预提交钩子：仅验证即将提交的文件。
• 基线：将收集的注释与基线过滤，以忽略旧的技术债务并关注新问题。

输出示例

安装

要安装 Comment Density Analyzer，请在您的终端运行以下命令

composer require --dev savinmikhail/comments-density

用法

使用以下命令分析您的 PHP 文件的注释密度

php vendor/bin/comments_density analyze:comments

使用以下命令生成基线

php vendor/bin/comments_density generate:baseline

配置

在安装时，您可以选择允许插件创建其配置文件。通过编辑 comments_density.php 配置文件来自定义分析。

<?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
];

致谢

本项目受到了 Yegor Bugayenko 的启发。请参阅 开源想法。

贡献

欢迎贡献！请随意提交 Pull Request。

许可

本库遵循 MIT 许可证。