Excellent 项目技术文档

1. 安装指南

1.1 使用 RubyGems 安装

要安装 Excellent 工具，只需使用 RubyGems 进行安装：

gem install excellent

1.2 配置文件

在项目根目录下创建一个 .excellent.yml 文件，用于配置需要运行的检查和阈值等。默认情况下，所有检查都是启用的，但你也可以通过配置文件禁用某些检查。例如：

AbcMetricMethodCheck: true
AssignmentInConditionalCheck: false

某些检查还可以接受配置，如阈值、模式等。你可以通过在 YAML 文件中定义嵌套的哈希来配置这些选项：

ClassLineCountCheck:
  threshold: 500
MethodNameCheck:
  pattern: '^[a-z].*'

1.3 忽略路径

你可以在项目根目录下创建一个 .excellentignore 文件，指定需要忽略的目录或文件。例如：

vendor
some/specific/file.rb

2. 项目的使用说明

2.1 基本用法

假设你有一个类定义如下：

class ShoppingBasket < ActiveRecord::Base

  def initialize(items = [])
    self.items = items
  end

end

使用 Excellent 工具可以检测出代码中的问题：

$ excellent shopping_basket.rb

  Excellent result:

  test.rb
    * Line   1: ShoppingBasket does not validate any attributes.
    * Line   1: ShoppingBasket defines initialize method.
    * Line   1: ShoppingBasket does not specify attr_accessible.

  Found 3 warnings.

2.2 分析 Rails 应用中的所有模型

你可以在 Rails 应用的根目录下运行以下命令，分析所有模型：

excellent app/models

2.3 生成 HTML 报告

你可以通过指定 html:<filename> 来生成格式化的 HTML 报告：

excellent -o out.html app/models

2.4 在 Rake 任务中使用

你还可以在 Rake 任务中使用 Excellent：

require 'simplabs/excellent/rake'

Simplabs::Excellent::Rake::ExcellentTask.new(:excellent) do |t|
  t.html  = 'doc/excellent.html' # 可选，如果不指定 html，输出将写入 $stdout
  t.paths = %w(app lib)
end

3. 项目API使用文档

3.1 获取启用的检查列表

你可以通过运行以下命令获取当前启用的检查及其配置：

excellent --checks

3.2 配置文件优先级

你可以在用户主目录下放置一个 .excellent.yml 文件，其中包含你希望始终应用的默认设置。项目特定的配置文件中的设置将覆盖这些默认设置。

4. 项目安装方式

4.1 通过 RubyGems 安装

最简单的安装方式是通过 RubyGems：

gem install excellent

4.2 配置文件

在项目根目录下创建 .excellent.yml 文件，配置需要运行的检查和阈值等。

4.3 忽略路径

在项目根目录下创建 .excellentignore 文件，指定需要忽略的目录或文件。

5. 静态代码分析

静态代码分析工具如 Excellent 无法真正理解代码，它们只是搜索可能指示问题的模式。因此，静态分析通常会返回一定数量的误报。不要试图编写代码以通过 Excellent 检查而不产生任何警告，这可能会使你的代码变得混乱。相反，使用 Excellent 作为帮助工具，尽早发现潜在的问题代码。

6. 作者

Excellent 由 simplabs GmbH 和贡献者开发，基于 MIT 许可证发布。该项目受到 roodi、reek 和 flog 的启发。