{"id":13633455,"url":"https://github.com/uohzxela/clean-code-ruby","last_synced_at":"2025-05-15T20:04:36.777Z","repository":{"id":39617658,"uuid":"102773976","full_name":"uohzxela/clean-code-ruby","owner":"uohzxela","description":"🛁 Clean Code concepts adapted for Ruby","archived":false,"fork":false,"pushed_at":"2022-09-10T02:38:29.000Z","size":321,"stargazers_count":1597,"open_issues_count":6,"forks_count":163,"subscribers_count":56,"default_branch":"master","last_synced_at":"2025-04-08T02:39:17.508Z","etag":null,"topics":["best-practices","clean-code","ruby"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/uohzxela.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2017-09-07T18:50:10.000Z","updated_at":"2025-04-04T20:08:07.000Z","dependencies_parsed_at":"2022-08-09T15:06:55.199Z","dependency_job_id":null,"html_url":"https://github.com/uohzxela/clean-code-ruby","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uohzxela%2Fclean-code-ruby","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uohzxela%2Fclean-code-ruby/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uohzxela%2Fclean-code-ruby/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/uohzxela%2Fclean-code-ruby/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/uohzxela","download_url":"https://codeload.github.com/uohzxela/clean-code-ruby/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254414499,"owners_count":22067272,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["best-practices","clean-code","ruby"],"created_at":"2024-08-01T23:00:44.751Z","updated_at":"2025-05-15T20:04:30.143Z","avatar_url":"https://github.com/uohzxela.png","language":"Ruby","readme":"# clean-code-ruby\n\nClean Code concepts adapted for Ruby.\n\nInspired by [clean-code-javascript](https://github.com/ryanmcdermott/clean-code-javascript).\n\n*Note: The examples are largely ported over from JavaScript so they may not be idiomatic. Feel free to point out any non-idiomatic Ruby code by submitting an issue and I'll correct it right away. Also, pull requests are always welcome!*\n\n## Table of Contents\n  1. [Introduction](#introduction)\n  2. [Variables](#variables)\n  3. [Methods](#methods)\n  4. [Objects and Data Structures](#objects-and-data-structures)\n  5. [Classes](#classes)\n  6. [SOLID](#solid)\n  7. [Testing](#testing)\n  9. [Error Handling](#error-handling)\n  10. [Formatting](#formatting)\n  11. [Comments](#comments)\n  12. [Translations](#translations)\n\n## Introduction\n![Humorous image of software quality estimation as a count of how many expletives\nyou shout when reading code](http://www.osnews.com/images/comics/wtfm.jpg)\n\nSoftware engineering principles, from Robert C. Martin's book\n[*Clean Code*](https://www.amazon.com/Clean-Code-Handbook-Software-Craftsmanship/dp/0132350882),\nadapted for Ruby. This is not a style guide. It's a guide to producing\n[readable, reusable, and refactorable](https://github.com/ryanmcdermott/3rs-of-software-architecture) software in Ruby.\n\nNot every principle herein has to be strictly followed, and even fewer will be\nuniversally agreed upon. These are guidelines and nothing more, but they are\nones codified over many years of collective experience by the authors of\n*Clean Code*.\n\nOur craft of software engineering is just a bit over 50 years old, and we are\nstill learning a lot. When software architecture is as old as architecture\nitself, maybe then we will have harder rules to follow. For now, let these\nguidelines serve as a touchstone by which to assess the quality of the\nRuby code that you and your team produce.\n\nOne more thing: knowing these won't immediately make you a better software\ndeveloper, and working with them for many years doesn't mean you won't make\nmistakes. Every piece of code starts as a first draft, like wet clay getting\nshaped into its final form. Finally, we chisel away the imperfections when\nwe review it with our peers. Don't beat yourself up for first drafts that need\nimprovement. Beat up the code instead!\n\n## **Variables**\n### Use meaningful and pronounceable variable names\n\n**Bad:**\n```ruby\nyyyymmdstr = Time.now.strftime('%Y/%m/%d')\n```\n\n**Good:**\n```ruby\ncurrent_date = Time.now.strftime('%Y/%m/%d')\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Use the same vocabulary for the same type of variable\n\nPick one word for the concept and stick to it.\n\n**Bad:**\n```ruby\nuser_info\nuser_data\nuser_record\n\nstarts_at\nstart_at\nstart_time\n```\n\n**Good:**\n```ruby\nuser\n\nstarts_at\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Use searchable names and use constants\nWe will read more code than we will ever write. It's important that the code we\ndo write is readable and searchable. By *not* naming variables that end up\nbeing meaningful for understanding our program, we hurt our readers.\nMake your names searchable.\n\nAlso, instead of hardcoding values and using \"magic numbers\", create constants.\n\n**Bad:**\n```ruby\n# What the heck is 86400 for?\nstatus = Timeout::timeout(86_400) do\n  # ...\nend\n```\n\n**Good:**\n```ruby\n# Declare them as capitalized globals.\nSECONDS_IN_A_DAY = 86_400\n\nstatus = Timeout::timeout(SECONDS_IN_A_DAY) do\n  # ...\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Use explanatory variables\n**Bad:**\n```ruby\naddress = 'One Infinite Loop, Cupertino 95014'\ncity_zip_code_regex = /^[^,\\\\]+[,\\\\\\s]+(.+?)\\s*(\\d{5})?$/\nsave_city_zip_code(city_zip_code_regex.match(address)[1], city_zip_code_regex.match(address)[2])\n```\n\n**Good:**\n```ruby\naddress = 'One Infinite Loop, Cupertino 95014'\ncity_zip_code_regex = /^[^,\\\\]+[,\\\\\\s]+(.+?)\\s*(\\d{5})?$/\n_, city, zip_code = city_zip_code_regex.match(address).to_a\nsave_city_zip_code(city, zip_code)\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Avoid Mental Mapping\nExplicit is better than implicit.\n\n**Bad:**\n```ruby\nlocations = ['Austin', 'New York', 'San Francisco']\nlocations.each do |l|\n  do_stuff\n  do_some_other_stuff\n  # ...\n  # ...\n  # ...\n  # Wait, what is `l` for again?\n  dispatch(l)\nend\n```\n\n**Good:**\n```ruby\nlocations = ['Austin', 'New York', 'San Francisco']\nlocations.each do |location|\n  do_stuff\n  do_some_other_stuff\n  # ...\n  # ...\n  # ...\n  dispatch(location)\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Don't add unneeded context\nIf your class/object name tells you something, don't repeat that in your\nvariable name.\n\n**Bad:**\n```ruby\ncar = {\n  car_make: 'Honda',\n  car_model: 'Accord',\n  car_color: 'Blue'\n}\n\ndef paint_car(car)\n  car[:car_color] = 'Red'\nend\n```\n\n**Good:**\n```ruby\ncar = {\n  make: 'Honda',\n  model: 'Accord',\n  color: 'Blue'\n}\n\ndef paint_car(car)\n  car[:color] = 'Red'\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Use default arguments instead of short circuiting or conditionals\nDefault arguments are often cleaner than short circuiting. Be aware that if you use them, your method will only provide default values for undefined arguments. Other \"falsy\" values such as `false` and `nil` will not be replaced by a default value.\n\n**Bad:**\n```ruby\ndef create_micro_brewery(name)\n  brewery_name = name || 'Hipster Brew Co.'\n  # ...\nend\n```\n\n**Good:**\n```ruby\ndef create_micro_brewery(brewery_name = 'Hipster Brew Co.')\n  # ...\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n## **Methods**\n### Method arguments (2 or fewer ideally)\nLimiting the amount of method parameters is incredibly important because it\nmakes testing your method easier. Having more than three leads to a\ncombinatorial explosion where you have to test tons of different cases with\neach separate argument.\n\nOne or two arguments is the ideal case, and three should be avoided if possible.\nAnything more than that should be consolidated. Usually, if you have\nmore than two arguments then your method is trying to do too much. In cases\nwhere it's not, most of the time a higher-level object will suffice as an\nargument. Or you can pass data to the method by instance variables.\n\nSince Ruby allows you to make objects on the fly, without a lot of class\nboilerplate, you can use an object if you are finding yourself needing a\nlot of arguments. The prevailing pattern in Ruby is to use a hash of arguments.\n\nTo make it obvious what properties the method expects, you can use the keyword arguments syntax (introduced in Ruby 2.1). This has a few advantages:\n\n1. When someone looks at the method signature, it's immediately clear what\nproperties are being used.\n2. If a required keyword argument is missing, Ruby will raise a useful `ArgumentError` that tells us which required argument we must include.\n\n**Bad:**\n```ruby\ndef create_menu(title, body)\n  # ...\nend\n\ncreate_menu('Foo', 'Bar')\n```\n\n**Good:**\n```ruby\ndef create_menu(title:, body:)\n  # ...\nend\n\ncreate_menu(title: 'Foo', body: 'Bar')\n```\n**[⬆ back to top](#table-of-contents)**\n\n\n### Methods should do one thing\nThis is by far the most important rule in software engineering. When methods\ndo more than one thing, they are harder to compose, test, and reason about.\nWhen you can isolate a method to just one action, they can be refactored\neasily and your code will read much cleaner. If you take nothing else away from\nthis guide other than this, you'll be ahead of many developers.\n\n**Bad:**\n```ruby\ndef email_clients(clients)\n  clients.each do |client|\n    client_record = database.lookup(client)\n    email(client) if client_record.active?\n  end\nend\n\nemail_clients(clients)\n```\n\n**Good:**\n```ruby\ndef email_clients(clients)\n  clients.each { |client| email(client) }\nend\n\ndef active(objects)\n  objects.select { |object| active?(object) }\nend\n\ndef active?(object)\n  record = database.lookup(object)\n  record.active?\nend\n\nemail_clients(active(clients))\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Method names should say what they do\nPoorly named methods add to the code reviewer's cognitive load at best, and mislead the\ncode reviewer at worst. Strive to capture the precise intent when naming methods.\n\n**Bad:**\n```ruby\ndef add_to_date(date, month)\n  # ...\nend\n\ndate = DateTime.now\n\n# It's hard to tell from the method name what is added\nadd_to_date(date, 1)\n```\n\n**Good:**\n```ruby\ndef add_month_to_date(date, month)\n  # ...\nend\n\ndate = DateTime.now\nadd_month_to_date(date, 1)\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Methods should only be one level of abstraction\nWhen you have more than one level of abstraction your method is usually\ndoing too much. Splitting up methods leads to reusability and easier\ntesting. Furthermore, methods should descend by the level of abstraction: one very abstract method should call methods that are less abstract and so on.\n\n**Bad:**\n```ruby\ndef interpret(code)\n  regexes = [\n    # ...\n  ]\n  statements = code.split(' ')\n\n  tokens = regexes.each_with_object([]) do |regex, memo|\n    statements.each do |statement|\n      # memo.push(...)\n    end\n  end\n\n  ast = tokens.map do |token|\n    # ...\n  end\n\n  ast.map do |node|\n    # ...\n  end\nend\n```\n\n**Good:**\n```ruby\ndef interpret(code)\n  tokens = tokenize(code)\n  ast = lex(tokens)\n  parse(ast)\nend\n\ndef tokenize(code)\n  regexes = [\n    # ...\n  ]\n  statements = code.split(' ')\n\n  regexes.each_with_object([]) do |regex, tokens|\n    statements.each do |statement|\n      # tokens.push(...)\n    end\n  end\nend\n\ndef lex(tokens)\n  tokens.map do |token|\n    # ...\n  end\nend\n\ndef parse(ast)\n  ast.map do |node|\n    # ...\n  end\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Remove duplicate code\nDo your absolute best to avoid duplicate code. Duplicate code is bad because it\nmeans that there's more than one place to alter something if you need to change\nsome logic.\n\nImagine if you run a restaurant and you keep track of your inventory: all your\ntomatoes, onions, garlic, spices, etc. If you have multiple lists that\nyou keep this on, then all have to be updated when you serve a dish with\ntomatoes in them. If you only have one list, there's only one place to update!\n\nOftentimes you have duplicate code because you have two or more slightly\ndifferent things, that share a lot in common, but their differences force you\nto have two or more separate methods that do much of the same things. Removing\nduplicate code means creating an abstraction that can handle this set of\ndifferent things with just one method/module/class.\n\nGetting the abstraction right is critical, that's why you should follow the\nSOLID principles laid out in the *Classes* section. Bad abstractions can be\nworse than duplicate code, so be careful! Having said this, if you can make\na good abstraction, do it! Don't repeat yourself, otherwise you'll find yourself\nupdating multiple places anytime you want to change one thing.\n\n**Bad:**\n```ruby\ndef show_developer_list(developers)\n  developers.each do |developer|\n    data = {\n      expected_salary: developer.expected_salary,\n      experience: developer.experience,\n      github_link: developer.github_link\n    }\n\n    render(data)\n  end\nend\n\ndef show_manager_list(managers)\n  managers.each do |manager|\n    data = {\n      expected_salary: manager.expected_salary,\n      experience: manager.experience,\n      portfolio: manager.mba_projects\n    }\n\n    render(data)\n  end\nend\n```\n\n**Good:**\n```ruby\ndef show_employee_list(employees)\n  employees.each do |employee|\n    data = build_data(employee)\n    render(data)\n  end\nend\n\ndef build_data(employee)\n  general_data = {\n    expected_salary: employee.expected_salary,\n    experience: employee.experience\n  }\n\n  general_data.merge(position_specific_data(employee))\nend\n\ndef position_specific_data(employee)\n  case employee.type\n  when 'manager'\n    { portfolio: employee.mba_projects }\n  when 'developer'\n    { github_link: employee.github_link }\n  end\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Don't use flags as method parameters\nFlags tell your user that this method does more than one thing. Methods should do one thing. Split out your methods if they are following different code paths based on a boolean.\n\n**Bad:**\n```ruby\ndef create_file(name, temp)\n  if temp\n    fs.create(\"./temp/#{name}\")\n  else\n    fs.create(name)\n  end\nend\n```\n\n**Good:**\n```ruby\ndef create_file(name)\n  fs.create(name)\nend\n\ndef create_temp_file(name)\n  create_file(\"./temp/#{name}\")\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Avoid Side Effects (part 1)\nA method produces side effects if it does anything more than take values and/or\nreturn values. A side effect could be writing to a file,\nmodifying some global variable, or accidentally wiring all your money to a\nstranger.\n\nNow, you do need to have side effects in a program on occasion. Like the previous\nexample, you might need to write to a file. What you want to do is to\ncentralize where you are doing this. Don't have several methods and classes\nthat write to a particular file. Have one service that does it. One and only one.\n\nThe main point is to avoid common pitfalls like sharing state between objects\nwithout any structure, using mutable data types that can be written to by anything,\nand not centralizing where your side effects occur. If you can do this, you will\nbe happier than the vast majority of other programmers.\n\n**Bad:**\n```ruby\n# Global variable referenced by following method.\n# If we had another method that used this name, now it'd be an array and it could break it.\n$name = 'Ryan McDermott'\n\ndef split_into_first_and_last_name\n  $name = $name.split(' ')\nend\n\nsplit_into_first_and_last_name()\n\nputs $name # ['Ryan', 'McDermott']\n```\n\n**Good:**\n```ruby\ndef split_into_first_and_last_name(name)\n  name.split(' ')\nend\n\nname = 'Ryan McDermott'\nfirst_and_last_name = split_into_first_and_last_name(name)\n\nputs name # 'Ryan McDermott'\nputs first_and_last_name # ['Ryan', 'McDermott']\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Avoid Side Effects (part 2)\nIn Ruby, everything is an object and everything is passed by value, but these values are references to objects. In the case of objects and arrays, if your method makes a change\nin a shopping cart array, for example, by adding an item to purchase,\nthen any other method that uses that `cart` array will be affected by this\naddition. That may be great, however it can be bad too. Let's imagine a bad\nsituation:\n\nThe user clicks the \"Purchase\", button which calls a `purchase` method that\nspawns a network request and sends the `cart` array to the server. Because\nof a bad network connection, the `purchase` method has to keep retrying the\nrequest. Now, what if in the meantime the user accidentally clicks \"Add to Cart\"\nbutton on an item they don't actually want before the network request begins?\nIf that happens and the network request begins, then that purchase method\nwill send the accidentally added item because it has a reference to a shopping\ncart array that the `add_item_to_cart` method modified by adding an unwanted\nitem.\n\nA great solution would be for the `add_item_to_cart` to always clone the `cart`,\nedit it, and return the clone. This ensures that no other methods that are\nholding onto a reference of the shopping cart will be affected by any changes.\n\nTwo caveats to mention to this approach:\n  1. There might be cases where you actually want to modify the input object,\nbut when you adopt this programming practice you will find that those cases\nare pretty rare. Most things can be refactored to have no side effects!\n\n  2. Cloning big objects can be very expensive in terms of performance. Luckily,\nthis isn't a big issue in practice because there are\n[great gems](https://github.com/hamstergem/hamster) that allow\nthis kind of programming approach to be fast and not as memory intensive as\nit would be for you to manually clone objects and arrays.\n\n**Bad:**\n```ruby\ndef add_item_to_cart(cart, item)\n  cart.push(item: item, time: Time.now)\nend\n```\n\n**Good:**\n```ruby\ndef add_item_to_cart(cart, item)\n  cart + [{ item: item, time: Time.now }]\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Favor functional programming over imperative programming\nRuby isn't a functional language in the way that Haskell is, but it has\na functional flavor to it. Functional languages are cleaner and easier to test.\nFavor this style of programming when you can.\n\n**Bad:**\n```ruby\nprogrammer_output = [\n  {\n    name: 'Uncle Bobby',\n    lines_of_code: 500\n  }, {\n    name: 'Suzie Q',\n    lines_of_code: 1500\n  }, {\n    name: 'Jimmy Gosling',\n    lines_of_code: 150\n  }, {\n    name: 'Grace Hopper',\n    lines_of_code: 1000\n  }\n]\n\ntotal_output = 0\n\nprogrammer_output.each do |output|\n  total_output += output[:lines_of_code]\nend\n```\n\n**Good:**\n```ruby\nprogrammer_output = [\n  {\n    name: 'Uncle Bobby',\n    lines_of_code: 500\n  }, {\n    name: 'Suzie Q',\n    lines_of_code: 1500\n  }, {\n    name: 'Jimmy Gosling',\n    lines_of_code: 150\n  }, {\n    name: 'Grace Hopper',\n    lines_of_code: 1000\n  }\n]\n\nINITIAL_VALUE = 0\n\ntotal_output = programmer_output.sum(INITIAL_VALUE) { |output| output[:lines_of_code] }\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Encapsulate conditionals\n\n**Bad:**\n```ruby\nif params[:message].present? \u0026\u0026 params[:recipient].present?\n  # ...\nend\n```\n\n**Good:**\n```ruby\ndef send_message?(params)\n  params[:message].present? \u0026\u0026 params[:recipient].present?\nend\n\nif send_message?(params)\n  # ...\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Avoid negative conditionals\n\n**Bad:**\n```ruby\nif !genres.blank?\n  # ...\nend\n```\n\n**Good:**\n```ruby\nunless genres.blank?\n  # ...\nend\n\n# or\n\nif genres.present?\n  # ...\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Avoid conditionals\nThis seems like an impossible task. Upon first hearing this, most people say,\n\"how am I supposed to do anything without an `if` statement?\" The answer is that\nyou can use polymorphism to achieve the same task in many cases. The second\nquestion is usually, \"well that's great but why would I want to do that?\" The\nanswer is a previous clean code concept we learned: a method should only do\none thing. When you have classes and methods that have `if` statements, you\nare telling your user that your method does more than one thing. Remember,\njust do one thing.\n\n**Bad:**\n```ruby\nclass Airplane\n  # ...\n  def cruising_altitude\n    case @type\n    when '777'\n      max_altitude - passenger_count\n    when 'Air Force One'\n      max_altitude\n    when 'Cessna'\n      max_altitude - fuel_expenditure\n    end\n  end\nend\n```\n\n**Good:**\n```ruby\nclass Airplane\n  # ...\nend\n\nclass Boeing777 \u003c Airplane\n  # ...\n  def cruising_altitude\n    max_altitude - passenger_count\n  end\nend\n\nclass AirForceOne \u003c Airplane\n  # ...\n  def cruising_altitude\n    max_altitude\n  end\nend\n\nclass Cessna \u003c Airplane\n  # ...\n  def cruising_altitude\n    max_altitude - fuel_expenditure\n  end\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Avoid type-checking (part 1)\nRuby is dynamically typed, which means your methods can take any type of argument.\nSometimes you are bitten by this freedom and it becomes tempting to do\ntype-checking in your methods. There are many ways to avoid having to do this.\nThe first thing to consider is consistent APIs.\n\n**Bad:**\n```ruby\ndef travel_to_texas(vehicle)\n  if vehicle.is_a?(Bicycle)\n    vehicle.pedal(@current_location, Location.new('texas'))\n  elsif vehicle.is_a?(Car)\n    vehicle.drive(@current_location, Location.new('texas'))\n  end\nend\n```\n\n**Good:**\n```ruby\ndef travel_to_texas(vehicle)\n  vehicle.move(@current_location, Location.new('texas'))\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Avoid type-checking (part 2)\nIf you are working with basic values like strings and integers,\nand you can't use polymorphism but you still feel the need to type-check,\nyou should consider using [contracts.ruby](https://github.com/egonSchiele/contracts.ruby). The problem with manually type-checking Ruby is that\ndoing it well requires so much extra verbiage that the faux \"type-safety\" you get\ndoesn't make up for the lost readability. Keep your Ruby clean, write\ngood tests, and have good code reviews.\n\n**Bad:**\n```ruby\ndef combine(val1, val2)\n  if (val1.is_a?(Numeric) \u0026\u0026 val2.is_a?(Numeric)) ||\n     (val1.is_a?(String) \u0026\u0026 val2.is_a?(String))\n    return val1 + val2\n  end\n\n  raise 'Must be of type String or Numeric'\nend\n```\n\n**Good:**\n```ruby\ndef combine(val1, val2)\n  val1 + val2\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Remove dead code\nDead code is just as bad as duplicate code. There's no reason to keep it in\nyour codebase. If it's not being called, get rid of it! It will still be safe\nin your version history if you still need it.\n\n**Bad:**\n```ruby\ndef old_request_module(url)\n  # ...\nend\n\ndef new_request_module(url)\n  # ...\nend\n\nreq = new_request_module(request_url)\ninventory_tracker('apples', req, 'www.inventory-awesome.io')\n```\n\n**Good:**\n```ruby\ndef new_request_module(url)\n  # ...\nend\n\nreq = new_request_module(request_url)\ninventory_tracker('apples', req, 'www.inventory-awesome.io')\n```\n**[⬆ back to top](#table-of-contents)**\n\n## **Objects and Data Structures**\n### Use getters and setters\nUsing getters and setters to access data on objects could be better than simply\nlooking for a property on an object. \"Why?\" you might ask. Well, here's an\nunorganized list of reasons why:\n\n* When you want to do more beyond getting an object property, you don't have\nto look up and change every accessor in your codebase.\n* Makes adding validation simple when doing a `set`.\n* Encapsulates the internal representation.\n* Easy to add logging and error handling when getting and setting.\n* You can lazy load your object's properties, let's say getting it from a\nserver.\n\n\n**Bad:**\n```ruby\ndef make_bank_account\n  # ...\n\n  {\n    balance: 0\n    # ...\n  }\nend\n\naccount = make_bank_account\naccount[:balance] = 100\naccount[:balance] # =\u003e 100\n```\n\n**Good:**\n```ruby\nclass BankAccount\n  def initialize\n    # this one is private\n    @balance = 0\n  end\n\n  # a \"getter\" via a public instance method\n  def balance\n    # do some logging\n    @balance\n  end\n\n  # a \"setter\" via a public instance method\n  def balance=(amount)\n    # do some logging\n    # do some validation\n    @balance = amount\n  end\nend\n\naccount = BankAccount.new\naccount.balance = 100\naccount.balance # =\u003e 100\n```\n\nAlternatively, if your getters and setters are absolutely trivial, you should use `attr_accessor` to define them. This is especially convenient for implementing data-like objects which expose data to other parts of the system (e.g., ActiveRecord objects, response wrappers for remote APIs).\n\n**Good:**\n```ruby\nclass Toy\n  attr_accessor :price\nend\n\ntoy = Toy.new\ntoy.price = 50\ntoy.price # =\u003e 50\n```\n\nHowever, you have to be aware that in some situations, using `attr_accessor` is a code smell, read more [here](https://solnic.codes/2012/04/04/get-rid-of-that-code-smell-attributes).\n\n**[⬆ back to top](#table-of-contents)**\n\n\n## **Classes**\n\n### Avoid fluent interfaces\nA [Fluent interface](https://en.wikipedia.org/wiki/Fluent_interface) is an object\noriented API that aims to improve the readability of the source code by using\n[method chaining](https://en.wikipedia.org/wiki/Method_chaining).\n\nWhile there can be some contexts, frequently builder objects, where this\npattern reduces the verbosity of the code (e.g., ActiveRecord queries),\nmore often it comes at some costs:\n\n1. Breaks [Encapsulation](https://en.wikipedia.org/wiki/Encapsulation_%28object-oriented_programming%29)\n2. Breaks [Decorators](https://en.wikipedia.org/wiki/Decorator_pattern)\n3. Is harder to [mock](https://en.wikipedia.org/wiki/Mock_object) in a test suite\n4. Makes diffs of commits harder to read\n\nFor more information you can read the full [blog post](https://ocramius.github.io/blog/fluent-interfaces-are-evil/)\non this topic written by [Marco Pivetta](https://github.com/Ocramius).\n\n**Bad:**\n```ruby\nclass Car\n  def initialize(make, model, color)\n    @make = make\n    @model = model\n    @color = color\n    # NOTE: Returning self for chaining\n    self\n  end\n\n  def set_make(make)\n    @make = make\n    # NOTE: Returning self for chaining\n    self\n  end\n\n  def set_model(model)\n    @model = model\n    # NOTE: Returning self for chaining\n    self\n  end\n\n  def set_color(color)\n    @color = color\n    # NOTE: Returning self for chaining\n    self\n  end\n\n  def save\n    # save object...\n    # NOTE: Returning self for chaining\n    self\n  end\nend\n\ncar = Car.new('Ford','F-150','red')\n  .set_color('pink')\n  .save\n```\n\n**Good:**\n```ruby\nclass Car\n  attr_accessor :make, :model, :color\n\n  def initialize(make, model, color)\n    @make = make\n    @model = model\n    @color = color\n  end\n\n  def save\n    # Save object...\n  end\nend\n\ncar = Car.new('Ford', 'F-150', 'red')\ncar.color = 'pink'\ncar.save\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Prefer composition over inheritance\nAs stated famously in [*Design Patterns*](https://en.wikipedia.org/wiki/Design_Patterns) by the Gang of Four,\nyou should prefer composition over inheritance where you can. There are lots of\ngood reasons to use inheritance and lots of good reasons to use composition.\nThe main point for this maxim is that if your mind instinctively goes for\ninheritance, try to think if composition could model your problem better. In some\ncases, it can.\n\nYou might be wondering then, \"when should I use inheritance?\" It\ndepends on your problem at hand, but this is a decent list of when inheritance\nmakes more sense than composition:\n\n1. Your inheritance represents an \"is-a\" relationship and not a \"has-a\"\nrelationship (Human-\u003eAnimal vs. User-\u003eUserDetails).\n2. You can reuse code from the base classes (Humans can move like all animals).\n3. You want to make global changes to derived classes by changing a base class.\n(Change the caloric expenditure of all animals when they move).\n\n**Bad:**\n```ruby\nclass Employee\n  def initialize(name, email)\n    @name = name\n    @email = email\n  end\n\n  # ...\nend\n\n# Bad because Employees \"have\" tax data. EmployeeTaxData is not a type of Employee\nclass EmployeeTaxData \u003c Employee\n  def initialize(ssn, salary)\n    @ssn = ssn\n    @salary = salary\n  end\n\n  # ...\nend\n```\n\n**Good:**\n```ruby\nclass EmployeeTaxData\n  def initialize(ssn, salary)\n    @ssn = ssn\n    @salary = salary\n  end\n\n  # ...\nend\n\nclass Employee\n  def initialize(name, email)\n    @name = name\n    @email = email\n  end\n\n  def set_tax_data(ssn, salary)\n    @tax_data = EmployeeTaxData.new(ssn, salary)\n  end\n  # ...\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n## **SOLID**\n### Single Responsibility Principle (SRP)\nAs stated in Clean Code, \"There should never be more than one reason for a class\nto change\". It's tempting to jam-pack a class with a lot of functionality, like\nwhen you can only take one suitcase on your flight. The issue with this is\nthat your class won't be conceptually cohesive and it will give it many reasons\nto change. Minimizing the number of times you need to change a class is important.\nIt's important because if too much functionality is in one class and you modify\na piece of it, it can be difficult to understand how that will affect other\ndependent modules in your codebase.\n\n**Bad:**\n```ruby\nclass UserSettings\n  def initialize(user)\n    @user = user\n  end\n\n  def change_settings(settings)\n    return unless valid_credentials?\n    # ...\n  end\n\n  def valid_credentials?\n    # ...\n  end\nend\n```\n\n**Good:**\n```ruby\nclass UserAuth\n  def initialize(user)\n    @user = user\n  end\n\n  def valid_credentials?\n    # ...\n  end\nend\n\nclass UserSettings\n  def initialize(user)\n    @user = user\n    @auth = UserAuth.new(user)\n  end\n\n  def change_settings(settings)\n    return unless @auth.valid_credentials?\n    # ...\n  end\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Open/Closed Principle (OCP)\nAs stated by [Bertrand Meyer](https://en.wikipedia.org/wiki/Bertrand_Meyer), \"software entities (classes, modules, functions,\netc.) should be open for extension, but closed for modification.\" What does that\nmean though? This principle basically states that you should allow users to\nadd new functionalities without changing existing code.\n\nIn the \"bad\" example below adding another adapter would require changing `HttpRequester` class. This violates OCP.\n\n**Bad:**\n```ruby\nclass AjaxAdapter\n  attr_reader :name\n\n  def initialize\n    @name = 'ajaxAdapter'\n  end\nend\n\nclass NodeAdapter\n  attr_reader :name\n\n  def initialize\n    @name = 'nodeAdapter'\n  end\nend\n\nclass HttpRequester\n  def initialize(adapter)\n    @adapter = adapter\n  end\n\n  def fetch(url)\n    case @adapter.name\n    when 'ajaxAdapter'\n      make_ajax_call(url)\n    when 'nodeAdapter'\n      make_http_call(url)\n    end\n  end\n\n  def make_ajax_call(url)\n    # ...\n  end\n\n  def make_http_call(url)\n    # ...\n  end\nend\n```\n\n**Good:**\n```ruby\nclass AjaxAdapter\n  def request(url)\n    # ...\n  end\nend\n\nclass NodeAdapter\n  def request(url)\n    # ...\n  end\nend\n\nclass HttpRequester\n  def initialize(adapter)\n    @adapter = adapter\n  end\n\n  def fetch(url)\n    @adapter.request(url)\n  end\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Liskov Substitution Principle (LSP)\nThis is a scary term for a very simple concept. It's formally defined as \"If S\nis a subtype of T, then objects of type T may be replaced with objects of type S\n(i.e., objects of type S may substitute objects of type T) without altering any\nof the desirable properties of that program (correctness, task performed,\netc.).\" That's an even scarier definition.\n\nThe best explanation for this is if you have a parent class and a child class,\nthen the base class can always be replaced by the child class without getting\nincorrect results. This might still be confusing, so let's take a look at the\nclassic Square-Rectangle example. Mathematically, a square is a rectangle, but\nif you model it using the \"is-a\" relationship via inheritance, you quickly\nget into trouble.\n\n**Bad:**\n```ruby\nclass Rectangle\n  def initialize\n    @width = 0\n    @height = 0\n  end\n\n  def color=(color)\n    # ...\n  end\n\n  def render(area)\n    # ...\n  end\n\n  def width=(width)\n    @width = width\n  end\n\n  def height=(height)\n    @height = height\n  end\n\n  def area\n    @width * @height\n  end\nend\n\nclass Square \u003c Rectangle\n  def width=(width)\n    @width = width\n    @height = width\n  end\n\n  def height=(height)\n    @width = height\n    @height = height\n  end\nend\n\ndef render_large_rectangles(rectangles)\n  rectangles.each do |rectangle|\n    rectangle.width = 4\n    rectangle.height = 5\n    area = rectangle.area # BAD: Returns 25 for Square. Should be 20.\n    rectangle.render(area)\n  end\nend\n\nrectangles = [Rectangle.new, Rectangle.new, Square.new]\nrender_large_rectangles(rectangles)\n```\n\n**Good:**\n```ruby\nclass Shape\n  def color=(color)\n    # ...\n  end\n\n  def render(area)\n    # ...\n  end\nend\n\nclass Rectangle \u003c Shape\n  def initialize(width, height)\n    @width = width\n    @height = height\n  end\n\n  def area\n    @width * @height\n  end\nend\n\nclass Square \u003c Shape\n  def initialize(length)\n    @length = length\n  end\n\n  def area\n    @length * @length\n  end\nend\n\ndef render_large_shapes(shapes)\n  shapes.each do |shape|\n    area = shape.area\n    shape.render(area)\n  end\nend\n\nshapes = [Rectangle.new(4, 5), Rectangle.new(4, 5), Square.new(5)]\nrender_large_shapes(shapes)\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Interface Segregation Principle (ISP)\nRuby doesn't have interfaces so this principle doesn't apply as strictly\nas others. However, it's important and relevant even with Ruby's lack of\ntype system.\n\nISP states that \"Clients should not be forced to depend upon interfaces that\nthey do not use.\" Interfaces are implicit contracts in Ruby because of\nduck typing.\n\nWhen a client depends upon a class that contains interfaces that the client does not use, but that other clients do use, then that client will be affected by the changes that those other clients force upon the class.\n\nThe following example is taken from [here](http://geekhmer.github.io/blog/2015/03/18/interface-segregation-principle-in-ruby/).\n\n**Bad:**\n```ruby\nclass Car\n  # used by Driver\n  def open\n    # ...\n  end\n\n  # used by Driver\n  def start_engine\n    # ...\n  end\n\n  # used by Mechanic\n  def change_engine\n    # ...\n  end\nend\n\nclass Driver\n  def drive\n    @car.open\n    @car.start_engine\n  end\nend\n\nclass Mechanic\n  def do_stuff\n    @car.change_engine\n  end\nend\n\n```\n\n**Good:**\n```ruby\n# used by Driver only\nclass Car\n  def open\n    # ...\n  end\n\n  def start_engine\n    # ...\n  end\nend\n\n# used by Mechanic only\nclass CarInternals\n  def change_engine\n    # ...\n  end\nend\n\nclass Driver\n  def drive\n    @car.open\n    @car.start_engine\n  end\nend\n\nclass Mechanic\n  def do_stuff\n    @car_internals.change_engine\n  end\nend\n```\n\n**[⬆ back to top](#table-of-contents)**\n\n### Dependency Inversion Principle (DIP)\nThis principle states two essential things:\n1. High-level modules should not depend on low-level modules. Both should\ndepend on abstractions.\n2. Abstractions should not depend upon details. Details should depend on\nabstractions.\n\nSimply put, DIP keeps high-level\nmodules from knowing the details of its low-level modules and setting them up.\nIt can accomplish this through dependency injection. A huge benefit of this is that\nit reduces the coupling between modules. Coupling is a very bad development pattern\nbecause it makes your code hard to refactor.\n\nAs stated previously, Ruby doesn't have interfaces so the abstractions\nthat are depended upon are implicit contracts. That is to say, the methods\nand properties that an object/class exposes to another object/class. In the\nexample below, the implicit contract is that any Request module for an\n`InventoryTracker` will have a `request_items` method.\n\n**Bad:**\n```ruby\nclass InventoryRequester\n  def initialize\n    @req_methods = ['HTTP']\n  end\n\n  def request_item(item)\n    # ...\n  end\nend\n\nclass InventoryTracker\n  def initialize(items)\n    @items = items\n\n    # BAD: We have created a dependency on a specific request implementation.\n    @requester = InventoryRequester.new\n  end\n\n  def request_items\n    @items.each do |item|\n      @requester.request_item(item)\n    end\n  end\nend\n\ninventory_tracker = InventoryTracker.new(['apples', 'bananas'])\ninventory_tracker.request_items\n```\n\n**Good:**\n```ruby\nclass InventoryTracker\n  def initialize(items, requester)\n    @items = items\n    @requester = requester\n  end\n\n  def request_items\n    @items.each do |item|\n      @requester.request_item(item)\n    end\n  end\nend\n\nclass InventoryRequesterV1\n  def initialize\n    @req_methods = ['HTTP']\n  end\n\n  def request_item(item)\n    # ...\n  end\nend\n\nclass InventoryRequesterV2\n  def initialize\n    @req_methods = ['WS']\n  end\n\n  def request_item(item)\n    # ...\n  end\nend\n\n# By constructing our dependencies externally and injecting them, we can easily\n# substitute our request module for a fancy new one that uses WebSockets.\ninventory_tracker = InventoryTracker.new(['apples', 'bananas'], InventoryRequesterV2.new)\ninventory_tracker.request_items\n```\n**[⬆ back to top](#table-of-contents)**\n\n## **Testing**\nTesting is more important than shipping. If you have no tests or an\ninadequate amount, then every time you ship code you won't be sure that you\ndidn't break anything. Deciding on what constitutes an adequate amount is up\nto your team, but having 100% coverage (all statements and branches) is how\nyou achieve very high confidence and developer peace of mind. This means that\nin addition to having a [great testing framework](http://rspec.info/), you also need to use a\n[good coverage tool](https://coveralls.io/).\n\nThere's no excuse to not write tests. Aim to always write tests\nfor every new feature/module you introduce. If your preferred method is\nTest Driven Development (TDD), that is great, but the main point is to just\nmake sure you are reaching your coverage goals before launching any feature,\nor refactoring an existing one.\n\n### Single expectation per test\n\n**Bad:**\n```ruby\nrequire 'rspec'\n\ndescribe 'Calculator' do\n  let(:calculator) { Calculator.new }\n\n  it 'performs addition, subtraction, multiplication and division' do\n    expect(calculator.calculate('1 + 2')).to eq(3)\n    expect(calculator.calculate('4 - 2')).to eq(2)\n    expect(calculator.calculate('2 * 3')).to eq(6)\n    expect(calculator.calculate('6 / 2')).to eq(3)\n  end\nend\n```\n\n**Good:**\n```ruby\nrequire 'rspec'\n\ndescribe 'Calculator' do\n  let(:calculator) { Calculator.new }\n\n  it 'performs addition' do\n    expect(calculator.calculate('1 + 2')).to eq(3)\n  end\n\n  it 'performs subtraction' do\n    expect(calculator.calculate('4 - 2')).to eq(2)\n  end\n\n  it 'performs multiplication' do\n    expect(calculator.calculate('2 * 3')).to eq(6)\n  end\n\n  it 'performs division' do\n    expect(calculator.calculate('6 / 2')).to eq(3)\n  end\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n## **Error Handling**\nThrown errors are a good thing! They mean the runtime has successfully\nidentified when something in your program has gone wrong and it's letting\nyou know by stopping method execution on the current stack, killing the\nprocess, and notifying you in the logs with a stack trace.\n\n### Don't ignore caught errors\nDoing nothing with a caught error doesn't give you the ability to ever fix\nor react to said error. Logging the error\nisn't much better as often times it can get lost in a sea of other logs. If you wrap any bit of code in a `begin/rescue` it means you\nthink an error may occur there and therefore you should have a plan,\nor create a code path, for when it occurs.\n\n**Bad:**\n```ruby\nrequire 'logger'\n\nlogger = Logger.new(STDOUT)\n\nbegin\n  method_that_might_throw()\nrescue StandardError =\u003e err\n  logger.info(err)\nend\n```\n\n**Good:**\n```ruby\nrequire 'logger'\n\nlogger = Logger.new(STDOUT)\n# Change the logger level to ERROR to output only logs with ERROR level and above\nlogger.level = Logger::ERROR\n\nbegin\n  method_that_might_throw()\nrescue StandardError =\u003e err\n  # Option 1: Only log errors\n  logger.error(err)\n  # Option 2: Notify end-user via an interface\n  notify_user_of_error(err)\n  # Option 3: Report error to a third-party service like Honeybadger\n  report_error_to_service(err)\n  # OR do all three!\nend\n```\n\n### Provide context with exceptions\nUse a descriptive error class name and a message when you raise an error. That way you know why the error occurred and you can rescue the specific type of error.\n\n***Bad:***\n```ruby\ndef initialize(user)\n  fail unless user\n  ...\nend\n```\n\n***Good:***\n```ruby\ndef initialize(user)\n  fail ArgumentError, 'Missing user' unless user\n  ...\nend\n```\n\n**[⬆ back to top](#table-of-contents)**\n\n\n## **Formatting**\nFormatting is subjective. Like many rules herein, there is no hard and fast\nrule that you must follow. The main point is DO NOT ARGUE over formatting.\nThere are tons of tools like [RuboCop](https://github.com/bbatsov/rubocop) to automate this.\nUse one! It's a waste of time and money for engineers to argue over formatting.\n\nFor things that don't fall under the purview of automatic formatting\n(indentation, tabs vs. spaces, double vs. single quotes, etc.) look here\nfor some guidance.\n\n### Use consistent capitalization\nRuby is dynamically typed, so capitalization tells you a lot about your variables,\nmethods, etc. These rules are subjective, so your team can choose whatever\nthey want. The point is, no matter what you all choose, just be consistent.\n\n**Bad:**\n```ruby\nDAYS_IN_WEEK = 7\ndaysInMonth = 30\n\nsongs = ['Back In Black', 'Stairway to Heaven', 'Hey Jude']\nArtists = ['ACDC', 'Led Zeppelin', 'The Beatles']\n\ndef eraseDatabase; end\n\ndef restore_database; end\n\nclass ANIMAL; end\nclass Alpaca; end\n```\n\n**Good:**\n```ruby\nDAYS_IN_WEEK = 7\nDAYS_IN_MONTH = 30\n\nSONGS = ['Back In Black', 'Stairway to Heaven', 'Hey Jude'].freeze\nARTISTS = ['ACDC', 'Led Zeppelin', 'The Beatles'].freeze\n\ndef erase_database; end\n\ndef restore_database; end\n\nclass Animal; end\nclass Alpaca; end\n```\n**[⬆ back to top](#table-of-contents)**\n\n\n### Method callers and callees should be close\nIf a method calls another, keep those methods vertically close in the source\nfile. Ideally, keep the caller right above the callee. We tend to read code from\ntop-to-bottom, like a newspaper. Because of this, make your code read that way.\n\n**Bad:**\n```ruby\nclass PerformanceReview\n  def initialize(employee)\n    @employee = employee\n  end\n\n  def lookup_peers\n    db.lookup(@employee, :peers)\n  end\n\n  def lookup_manager\n    db.lookup(@employee, :manager)\n  end\n\n  def peer_reviews\n    peers = lookup_peers\n    # ...\n  end\n\n  def perf_review\n    peer_reviews\n    manager_review\n    self_review\n  end\n\n  def manager_review\n    manager = lookup_manager\n    # ...\n  end\n\n  def self_review\n    # ...\n  end\nend\n\nreview = PerformanceReview.new(employee)\nreview.perf_review\n```\n\n**Good:**\n```ruby\nclass PerformanceReview\n  def initialize(employee)\n    @employee = employee\n  end\n\n  def perf_review\n    peer_reviews\n    manager_review\n    self_review\n  end\n\n  def peer_reviews\n    peers = lookup_peers\n    # ...\n  end\n\n  def lookup_peers\n    db.lookup(@employee, :peers)\n  end\n\n  def manager_review\n    manager = lookup_manager\n    # ...\n  end\n\n  def lookup_manager\n    db.lookup(@employee, :manager)\n  end\n\n  def self_review\n    # ...\n  end\nend\n\nreview = PerformanceReview.new(employee)\nreview.perf_review\n```\n\n**[⬆ back to top](#table-of-contents)**\n\n## **Comments**\n\n\n### Don't leave commented out code in your codebase\nVersion control exists for a reason. Leave old code in your history.\n\n**Bad:**\n```ruby\ndo_stuff\n# do_other_stuff\n# do_some_more_stuff\n# do_so_much_stuff\n```\n\n**Good:**\n```ruby\ndo_stuff\n```\n**[⬆ back to top](#table-of-contents)**\n\n### Don't have journal comments\nRemember, use version control! There's no need for dead code, commented code,\nand especially journal comments. Use `git log` to get history!\n\n**Bad:**\n```ruby\n# 2016-12-20: Removed monads, didn't understand them (RM)\n# 2016-10-01: Improved using special monads (JP)\n# 2016-02-03: Removed type-checking (LI)\n# 2015-03-14: Added combine with type-checking (JR)\ndef combine(a, b)\n  a + b\nend\n```\n\n**Good:**\n```ruby\ndef combine(a, b)\n  a + b\nend\n```\n**[⬆ back to top](#table-of-contents)**\n\n## Translations\n\nThis is also available in other languages:\n\n  - [Brazilian Portuguese](https://github.com/uohzxela/clean-code-ruby/blob/master/translations/pt-BR.md)\n  - [Simplified Chinese](https://github.com/uohzxela/clean-code-ruby/blob/master/translations/zh-CN.md)\n\n**[⬆ back to top](#table-of-contents)**\n","funding_links":[],"categories":["Ruby","其它代码整洁之道列表"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuohzxela%2Fclean-code-ruby","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fuohzxela%2Fclean-code-ruby","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fuohzxela%2Fclean-code-ruby/lists"}