Nâng cao chất lượng code Ruby: Linting & Auto-Formatting với RuboCop

Linting là việc kiểm tra tự động mã nguồn để tìm lỗi lập trình và phong cách. Việc kiểm tra này được thực hiện bởi công cụ phân tích code tĩnh gọi là linter. Một code formatter, tuy nhiên, là công cụ liên quan đến định dạng mã nguồn để nó tuân thủ chặt chẽ một tập quy tắc được cấu hình trước. Linter thường báo cáo vi phạm, nhưng thường để lập trình viên tự sửa, trong khi code formatter xu hướng áp dụng quy tắc trực tiếp vào mã nguồn, từ đó tự động sửa lỗi định dạng.

Nhiệm vụ tạo phong cách code nhất quán trong dự án thường đòi hỏi giới thiệu công cụ linting và formatting riêng biệt, nhưng trong một số trường hợp, một công cụ đơn lẻ có thể giải quyết cả hai vấn đề. Ví dụ tốt cho trường hợp sau là RuboCop, công cụ chúng ta sẽ xem xét kỹ trong bài này. Bạn sẽ học cách cài đặt nó trong dự án Ruby và điều chỉnh các tùy chọn cấu hình sao cho đầu ra phù hợp với kỳ vọng. Ngoài việc tích hợp vào quy trình phát triển cục bộ, bạn cũng sẽ học cách làm cho nó trở thành một phần của quy trình continuous integration.

Cài đặt RuboCop

Cài đặt RuboCop rất đơn giản qua RubyGems:

$ gem install rubocop

Kiểm tra phiên bản đã cài:

$ rubocop --version
1.18.3

Nếu bạn thích dùng Bundler, đặt đoạn sau vào Gemfile và chạy bundle install. Phần require: false báo cho Bundler.require không require gem đó trong code vì nó chỉ dùng từ dòng lệnh.

gem 'rubocop', require: false

Kiểm tra phiên bản:

$ bundle exec rubocop --version
1.18.3

Chạy RuboCop

Bạn có thể chạy RuboCop với cài đặt mặc định trên dự án bằng cách gõ rubocop (hoặc bundle exec rubocop nếu cài bằng Bundler). Nếu không truyền đối số, nó sẽ kiểm tra tất cả file Ruby trong thư mục hiện tại và các thư mục con. Thay vào đó, bạn có thể truyền danh sách file và thư mục cần phân tích.

$ bundle exec rubocop
$ bundle exec rubocop src/lib

Mặc định, RuboCop thực thi nhiều hướng dẫn trong Ruby Style Guide do cộng đồng dẫn dắt. Sau khi chạy, bạn có thể nhận được một số lỗi (offenses). Mỗi vi phạm được báo cáo đều đi kèm mọi thông tin cần thiết để giải quyết, như mô tả vi phạm, file và số dòng xảy ra.

Ở cuối báo cáo, bạn thấy dòng mô tả số file đã kiểm tra, tổng số vi phạm, và bao nhiêu vi phạm có thể tự động sửa. Nếu thêm đối số -a hoặc --auto-correct, RuboCop sẽ cố gắng tự động sửa các vấn đề tìm thấy (những cái có tiền tố [Correctable]).

$ bundle exec rubocop -a

Chú ý mỗi vi phạm đã sửa giờ có tiền tố [Corrected]. Tóm tắt số vi phạm đã sửa cũng xuất hiện ở cuối báo cáo. Trong ví dụ trên, còn một vi phạm có thể sửa nhưng không được auto-fix, ngay cả sau cờ -a. Điều này là vì một số sửa tự động có thể thay đổi ngữ nghĩa code nhẹ, nên RuboCop coi nó không an toàn. Nếu muốn auto-correct những vi phạm này nữa, dùng cờ -A hoặc --auto-correct-all.

$ bundle exec rubocop -A

Một quy tắc tốt là chạy test suite sau khi dùng autocorrect để đảm bảo hành vi code không thay đổi bất ngờ.

Cấu hình RuboCop

RuboCop có thể cấu hình qua file .rubocop.yml đặt ở gốc dự án. Nếu muốn dùng cùng kiểm tra cho mọi dự án, bạn có thể đặt file config toàn cục trong thư mục home (~/.rubocop.yml) hoặc thư mục config XDG (~/.config/rubocop/config.yml). File config toàn cục sẽ được dùng nếu file config cục bộ không tìm thấy trong thư mục hiện tại hoặc các thư mục cha.

Cấu hình mặc định của RuboCop đặt trong thư mục home config (~/.config/rubocop/default.yml), và mọi file config khác đều kế thừa từ nó. Điều này có nghĩa khi thiết lập config dự án, bạn chỉ cần thay đổi những gì khác với mặc định. Có thể là bật/tắt một số kiểm tra hoặc thay đổi hành vi nếu chúng chấp nhận tham số.

RuboCop gọi mỗi kiểm tra riêng lẻ là cops, mỗi cái chịu trách nhiệm phát hiện một vi phạm cụ thể. Các cops có sẵn cũng được nhóm thành các department sau:

• Style cops chủ yếu dựa trên Ruby Style Guide, kiểm tra tính nhất quán của code.
• Layout cops bắt lỗi liên quan đến định dạng, như sử dụng khoảng trắng.
• Lint cops phát hiện lỗi tiềm ẩn trong code, tương tự ruby -w, nhưng với nhiều kiểm tra thêm.
• Metric cops xử lý vấn đề liên quan đến đo lường code như độ dài class và method.
• Naming cops quan tâm đến quy ước đặt tên.
• Security cops giúp bắt các vấn đề bảo mật tiềm ẩn.
• Bundler cops kiểm tra thói quen xấu trong file Bundler (như Gemfile).
• Gemspec cops kiểm tra thói quen xấu trong file .gemspec.

Cũng có thể mở rộng RuboCop qua các linter và formatter bổ sung. Bạn có thể tự xây dựng extension hoặc tận dụng các extension hiện có nếu liên quan đến dự án. Ví dụ, extension Rails có sẵn để thực thi best practice và quy ước code Rails.

Khi tạo file cấu hình lần đầu, bạn sẽ nhận nhiều cảnh báo về các cops mới được thêm nhưng chưa cấu hình. Điều này vì RuboCop thêm cops mới mỗi release, và chúng được đặt ở trạng thái pending đặc biệt cho đến khi được bật/tắt rõ ràng trong config người dùng. Bạn có thể bật/tắt từng cops trong thông báo hoặc dùng đoạn sau để bật tất cả cops mới (khuyến nghị). Sau đó, thông báo sẽ bị ẩn.

# .rubocop.yml
AllCops:
  NewCops: enable

Nếu không muốn loay hoay với file cấu hình và nhiều tùy chọn của RuboCop, hãy xem dự án Standard. Nó chủ yếu là phiên bản RuboCop được cấu hình sẵn nhằm thực thi phong cách nhất quán trong dự án Ruby mà không cho phép tùy chỉnh quy tắc. Bài lightning talk nơi nó được công bố lần đầu đưa ra thêm chi tiết về nguồn gốc và động lực.

Bạn có thể cài bằng cách thêm dòng sau vào Gemfile và chạy bundle install.

# Gemfile
gem "standard", group: [:development, :test]

Sau đó, thực thi Standard từ dòng lệnh như sau:

$ bundle exec standardrb

Thêm RuboCop vào dự án đã tồn tại

Hầu hết Rubyists không có đặc quyền làm việc trên dự án greenfield. Nhiều thời gian phát triển dành cho codebase legacy có thể tạo ra lượng lớn vi phạm linting không thể xử lý ngay. May mắn thay, RuboCop có tính năng hữu ích tạo allowlist các vi phạm hiện có, có thể giải quyết dần theo thời gian. Lợi ích là cho phép giới thiệu linting vào dự án hiện có mà không bị bủa vây bởi núi lỗi linting khó quản lý trong khi vẫn gắn cờ các vi phạm mới từ nay về sau.

$ bundle exec rubocop
523 files inspected, 1018 offenses detected

Tạo file config allowlist bằng lệnh:

$ bundle exec rubocop --auto-gen-config
Added inheritance from `.rubocop_todo.yml` in `.rubocop.yml`.
Created .rubocop_todo.yml.

$ bundle exec rubocop
523 files inspected, no offenses detected

$ bundle exec rubocop --auto-gen-config --auto-gen-only-exclude --exclude-limit 10000

# Gemfile
gem "rubocop-shopify", require: false

# .rubocop.yml
inherit_gem:
  rubocop-shopify: rubocop.yml

# rubocop:disable Layout/LineLength, Style
[..]
# rubocop:enable Layout/LineLength, Style

# rubocop:disable all
[..]
# rubocop:enable all

for x in (0..10) # rubocop:disable Style/For

{
  "ruby.lint": {
    "rubocop": true
  }
}

{
  "coc.preferences.formatOnSaveFiletypes": ["ruby"],
  "solargraph.autoformat": true,
  "solargraph.diagnostics": true,
  "solargraph.formatting": true
}

$ gem install overcommit
$ overcommit --install # tại gốc dự án

# .overcommit.yml
PreCommit:
  RuboCop:
    enabled: true
    on_warn: fail
    problem_on_unmodified_line: ignore
    command: ['bundle', 'exec', 'rubocop']

$ SKIP=RuboCop git commit -m "WIP: Unfinished work"

# .github/workflows/rubocop.yml
name: Lint code with RuboCop
on: [push, pull_request]
jobs:
  build:
    runs-on: ${{ matrix.os }}
    strategy:
      matrix:
        os: [macos-latest, ubuntu-latest, windows-latest]
    steps:
      - uses: actions/checkout@v2
      - name: Setup Ruby
        uses: ruby/setup-ruby@v1
        with:
          ruby-version: '3.0'
          bundler-cache: true
      - name: Run RuboCop
        run: bundle exec rubocop

# Gemfile
gem 'prettier'

$ bundle exec rbprettier --write '**/*.rb'

# .rubocop.yml
inherit_gem:
  prettier: rubocop.yml