Extracts from "Clean Code"
- 1. Extracts from “Clean code” Vlatka Pavišić
- 2. Naming ❏ Choose descriptive, pronounceable and searchable names ❏ Classes should have a noun (phrase) name like Customer, AddressParser ❏ Avoid generic names like Data, Info, Processor ❏ Pick one word for the concept ❏ Examples of bad practices: using both start_at and starts_at at different tables; get, fetch and retrieve for the same action ❏ Use long names for long scopes; loop variables can have short names
- 3. Methods ❏ They should be small ❏ The number of arguments should be minimized ❏ By creating an object for the arguments ❏ By using instance variables ❏ Blocks within if-else should be 1 line long ❏ Have 1 level of abstraction per method ❏ Methods should descend by the level of abstraction ❏ They should have descriptive names even if they’re long ❏ Avoid boolean arguments. Instead, split the function in two ❏ A method should have no hidden side-effects (like a method check_password that also initializes a session)
- 4. Classes ❏ Classes should be small, not in the terms of the number of lines but the number of responsibilities ❏ Each small class encapsulates a single responsibility, has a single reason to change, and collaborates with a few others to achieve the desired system behaviours ❏ For example: Event, EventPresenter, EventsController, EventPolicy...
- 5. Comments ❏ Good code is like a good joke: it needs no explanation ❏ Instead of writing comments, try to express yourself with code ❏ It’s better to put in the effort to write expressive code than to update the comments when the code changes ❏ Exception: documentation tool (like YARD) - all public methods, classes, modules should have comments for documentation purposes
- 6. Formatting ❏ Separate different concepts and sections (in Rails’ models: associations, validations, scopes…) with blank lines ❏ The caller method should be above the callee and as close as possible ❏ Conceptual affinity - methods that do similar things should be close ❏ Vertical ordering - most important functions should come first ❏ Don’t do horizontal alignment (like in FactoryBot factories) because it tempts you to read it column by column ❏ Team should agree upon rules so that the project code is consistent
- 7. Error handling ❏ Provide context with exceptions; use a descriptive class name and a message
- 8. Tests ❏ Try to have one assert per test or at least to minimize their number ❏ Use a test coverage tool (for Ruby, simplecov) ❏ Test boundary conditions ❏ Tests should be fast
- 9. Code smells ❏ Obsolete, redundant or poorly written comments ❏ Commented-out code ❏ Methods with too many arguments ❏ Multiple programming languages in one file ❏ Duplication ❏ Dead code - code that’s never executed ❏ Inconsistency - doing similar things in a different way
- 10. Heuristics ❏ Simplify complex expressions ❏ With explanatory variables ❏ With encapsulating conditionals - like should_be_deleted ❏ Prefer polymorphism to if-else and switch-case ❏ Follow style guides and standard conventions ❏ https://github.com/bbatsov/ruby-style-guide ❏ https://github.com/bbatsov/rails-style-guide ❏ http://www.betterspecs.org ❏ Use constants for “magic numbers” ❏ Avoid negative conditionals (like !event.deadline_not_passed?)
- 11. Merci pour votre attention !