“Code as if the guy who ends up maintaining your code will be a violent psychopath who knows where you live”

John Woods

Introduction

1. Saves Time: When the code is easy to understand, it saves the time that would have been spent trying to decipher what it does.
2. Increases Collaboration: When code is well-documented, it makes it easier for multiple people to work on it and understand what's happening.
3. Increases Maintainability: A well-documented code is easier to maintain, which means it's more likely to continue to work correctly over time.

1. Use Descriptive and Meaningful Variable Names: Avoid using abbreviations or single-letter names for variables. Instead, use descriptive and meaningful names that explain what the variable is used for.
2. Write Clear and Concise Code: Avoid writing complex or overly verbose code. Instead, write clear and concise code so it's easy to understand what it does.
3. Use Appropriate Functions and Method Names: Use function and method names that explain the code's actions. This makes it easier for others to understand what the code does without looking at the implementation.
4. Use Comments: Use comments to explain what your code does, especially for complex or abstract code.

# Before:
class Invoice
  attr_reader :amt, :tax, :disc, :status

  def initialize(amt, tax, disc)
    @amt = amt
    @tax = tax
    @disc = disc
    @status = :unpaid
  end

  def ttl
    ttl = amt + amt * tax / 100
    ttl = ttl - ttl * disc / 100
    ttl
  end

  def pay
    @status = :paid
  end
end

# After:
class Invoice
  attr_reader :total_amount, :tax_percentage, :discount_percentage, :payment_status

  def initialize(total_amount, tax_percentage, discount_percentage)
    @total_amount = total_amount
    @tax_percentage = tax_percentage
    @discount_percentage = discount_percentage
    @payment_status = :unpaid
  end

  def calculate_total_with_tax_and_discount
    taxed_amount = total_amount + total_amount * tax_percentage / 100
    discounted_amount = taxed_amount - taxed_amount * discount_percentage / 100
    discounted_amount
  end

  def mark_as_paid
    @payment_status = :paid
  end
end