Ruby Best Practices

Testing and Code Coverage

• Write tests for all new code. No code changes should be accepted without corresponding test coverage. Prefer writing tests first using Test Driven Development (TDD).
• Mock all external API calls in tests. Never allow tests to make real network requests.
• Improve coverage when modifying existing code, especially for files with low coverage (e.g.,

  data_fetcher.rb

  ,

  github_client.rb

  ,

  html_generator.rb

  ).
• Always run the coverage report (

  bundle exec rake coverage

  ) to verify the impact of your changes.
• Place test files in the

  test/

  directory, use a

  _test.rb

  suffix, and require

  test_helper

  at the top.
• Follow the

  test_method_name

  pattern for test methods.
• Use Mocha’s

  mock

  and

  stubs

  for external dependencies.
• Use

  setup

  and

  teardown

  for test preparation and cleanup.
• Store fixtures in

  test/fixtures/

  .
• Add an empty line before each assertion method to comply with RuboCop’s Minitest/EmptyLineBeforeAssertionMethods rule and improve readability.
• Limit test methods to no more than 5 assertions. Split tests as needed and ensure each has independent setup.

Method Design and Complexity

• Each method should have a single, clear responsibility. If a method’s purpose requires “and” to describe, split it.
• Keep methods under 20 lines (excluding comments). Cyclomatic complexity should be under 7; perceived complexity under 8. Extract helper methods as needed.
• Use descriptive method names. Break lines longer than 100 characters using line continuation with

  \

  .
• Use guard clauses and early returns for edge cases.
• Extract validation, data transformation, and complex conditionals into dedicated, well-named helper methods.
• Always test newly extracted methods. If helpers are private, consider testable delegation in test environments.

Ruby Style and RuboCop Compliance

• Use 2 spaces for indentation, never tabs.
• Keep lines under 100 characters.
• Use spaces around operators, after commas, colons, and semicolons. No trailing whitespace at line ends or on blank lines.
• End each file with a newline.
• Use

  snake_case

  for variables, methods, and file names;

  CamelCase

  for classes/modules;

  SCREAMING_SNAKE_CASE

  for constants.
• Use single quotes for non-interpolated strings, double quotes for interpolated or special-character strings.
• Add

  # frozen_string_literal: true

  at the top of every file.
• Prefer early returns for error and edge cases.
• Use visibility modifiers (

  private

  ,

  protected

  ) to encapsulate implementation details.
• Group related methods together within classes/modules.
• Add comments for complex or non-obvious code. Document public methods, parameters, and return values.
• Rescue only specific exceptions, not

  Exception

  or bare

  rescue

  . Use descriptive messages for exceptions and log them appropriately.

Common RuboCop Offenses and Fixes

• Watch for and remove trailing whitespace, especially on blank

Sources