Extracts from the book 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 !