Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
7 comments

Expand on why let should be avoided

* Explain that re-implementing `let` is not the answer.
* Extract `let` and `let!` into its own guideline
* Provide better examples
latest commit ae1c6bb3a5
@gylaz gylaz authored

README.md

Best Practices

A guide for programming well.

General

  • These are not to be blindly followed; strive to understand these and ask when in doubt.
  • Don't duplicate the functionality of a built-in library.
  • Don't swallow exceptions or "fail silently."
  • Don't write code that guesses at future functionality.
  • Exceptions should be exceptional.
  • Keep the code simple.

Object-Oriented Design

  • Avoid global variables.
  • Avoid long parameter lists.
  • Limit collaborators of an object (entities an object depends on).
  • Limit an object's dependencies (entities that depend on an object).
  • Prefer composition over inheritance.
  • Prefer small methods. Between one and five lines is best.
  • Prefer small classes with a single, well-defined responsibility. When a class exceeds 100 lines, it may be doing too many things.
  • Tell, don't ask.

Ruby

  • Avoid optional parameters. Does the method do too much?
  • Avoid monkey-patching.
  • Generate necessary Bundler binstubs for the project, such as rake and rspec, and add them to version control.
  • Prefer classes to modules when designing functionality that is shared by multiple models.
  • Prefer private when indicating scope. Use protected only with comparison methods like def ==(other), def <(other), and def >(other).

Ruby Gems

  • Declare dependencies in the <PROJECT_NAME>.gemspec file.
  • Reference the gemspec in the Gemfile.
  • Use Appraisal to test the gem against multiple versions of gem dependencies (such as Rails in a Rails engine).
  • Use Bundler to manage the gem's dependencies.
  • Use Travis CI for Continuous Integration, indicators showing whether GitHub pull requests can be merged, and to test against multiple Ruby versions.

Rails

  • Add foreign key constraints in migrations.
  • Avoid bypassing validations with methods like save(validate: false), update_attribute, and toggle.
  • Avoid instantiating more than one object in controllers.
  • Avoid naming methods after database columns in the same class.
  • Don't change a migration after it has been merged into master if the desired change can be solved with another migration.
  • Don't reference a model class directly from a view.
  • Don't return false from ActiveModel callbacks, but instead raise an exception.
  • Don't use instance variables in partials. Pass local variables to partials from view templates.
  • Don't use SQL or SQL fragments (where('inviter_id IS NOT NULL')) outside of models.
  • Generate necessary Spring binstubs for the project, such as rake and rspec, and add them to version control.
  • If there are default values, set them in migrations.
  • Keep db/schema.rb or db/development_structure.sql under version control.
  • Use only one instance variable in each view.
  • Use SQL, not ActiveRecord models, in migrations.
  • Use the .ruby-version file convention to specify the Ruby version and patch level for a project.
  • Use _url suffixes for named routes in mailer views and redirects. Use _path suffixes for named routes everywhere else.
  • Validate the associated belongs_to object (user), not the database column (user_id).
  • Use db/seeds.rb for data that is required in all environments.
  • Use dev:prime rake task for development environment seed data.
  • Prefer cookies.signed over cookies to prevent tampering.
  • Prefer Time.current over Time.now
  • Prefer Date.current over Date.today
  • Prefer Time.zone.parse("2014-07-04 16:05:37") over Time.parse("2014-07-04 16:05:37")
  • Use ENV.fetch for environment variables instead of ENV[]so that unset environment variables are detected on deploy.

Testing

  • Avoid any_instance in rspec-mocks and mocha. Prefer dependency injection.
  • Avoid its, specify, and before in RSpec.
  • Avoid let (or let!) in RSpec. Prefer extracting helper methods, but do not re-implement the functionality of let. Example.
  • Avoid using subject explicitly inside of an RSpec it block. Example.
  • Avoid using instance variables in tests.
  • Disable real HTTP requests to external services with WebMock.disable_net_connect!.
  • Don't test private methods.
  • Test background jobs with a Delayed::Job matcher.
  • Use stubs and spies (not mocks) in isolated tests.
  • Use a single level of abstraction within scenarios.
  • Use an it example or test method for each execution path through the method.
  • Use assertions about state for incoming messages.
  • Use stubs and spies to assert you sent outgoing messages.
  • Use a Fake to stub requests to external services.
  • Use integration tests to execute the entire app.
  • Use non-SUT methods in expectations when possible.

Bundler

  • Specify the Ruby version to be used on the project in the Gemfile.
  • Use a pessimistic version in the Gemfile for gems that follow semantic versioning, such as rspec, factory_girl, and capybara.
  • Use a versionless Gemfile declarations for gems that are safe to update often, such as pg, thin, and debugger.
  • Use an exact version in the Gemfile for fragile gems, such as Rails.

Postgres

Background Jobs

  • Store IDs, not ActiveRecord objects for cleaner serialization, then re-find the ActiveRecord object in the perform method.

Email

  • Use SendGrid or Amazon SES to deliver email in staging and production environments.
  • Use a tool like ActionMailer Preview to look at each created or updated mailer view before merging. Use MailView gem unless using Rails version 4.1.0 or later.

JavaScript

  • Use Coffeescript, ES6 with babel, or another language that compiles to JavaScript
  • Include a to_param or href attribute when serializing ActiveRecord models, and use that when constructing URLs client side, rather than the ID. Example:

HTML

  • Don't use a reset button for forms.
  • Prefer cancel links to cancel buttons.
  • Use <button> tags over <a> tags for actions.

CSS

  • Use Sass.

Sass

  • Prefer overflow: auto to overflow: scroll, because scroll will always display scrollbars outside of OS X, even when content fits in the container.
  • Use image-url and font-url, not url, so the asset pipeline will re-write the correct paths to assets.
  • Prefer mixins to @extend.

Browsers

  • Don't support versions of Internet Explorer before IE9.

Objective-C

  • Setup new projects using Liftoff and follow provided directory structure.
  • Prefer categories on Foundation classes to helper methods.
  • Prefer string constants to literals when providing keys or key paths to methods.

Shell

  • Don't parse the output of ls. See here for details and alternatives.
  • Don't use cat to provide a file on stdin to a process that accepts file arguments itself.
  • Don't use echo with options, escapes, or variables (use printf for those cases).
  • Don't use a /bin/sh shebang unless you plan to test and run your script on at least: Actual Sh, Dash in POSIX-compatible mode (as it will be run on Debian), and Bash in POSIX-compatible mode (as it will be run on OSX).
  • Don't use any non-POSIX features when using a /bin/sh shebang.
  • If calling cd, have code to handle a failure to change directories.
  • If calling rm with a variable, ensure the variable is not empty.
  • Prefer "$@" over "$*" unless you know exactly what you're doing.
  • Prefer awk '/re/ { ... }' to grep re | awk '{ ... }'.
  • Prefer find -exec {} + to find -print0 | xargs -0.
  • Prefer for loops over while read loops.
  • Prefer grep -c to grep | wc -l.
  • Prefer mktemp over using $$ to "uniquely" name a temporary file.
  • Prefer sed '/re/!d; s//.../' to grep re | sed 's/re/.../'.
  • Prefer sed 'cmd; cmd' to sed -e 'cmd' -e 'cmd'.
  • Prefer checking exit statuses over output in if statements (if grep -q ...;, not if [ -n "$(grep ...)" ];).
  • Prefer reading environment variables over process output ($TTY not $(tty), $PWD not $(pwd), etc).
  • Use $( ... ), not backticks for capturing command output.
  • Use $(( ... )), not expr for executing arithmetic expressions.
  • Use 1 and 0, not true and false to represent boolean variables.
  • Use find -print0 | xargs -0, not find | xargs.
  • Use quotes around every "$variable" and "$( ... )" expression unless you want them to be word-split and/or interpreted as globs.
  • Use the local keyword with function-scoped variables.
  • Identify common problems with shellcheck.

Bash

In addition to Shell best practices,

  • Prefer ${var,,} and ${var^^} over tr for changing case.
  • Prefer ${var//from/to} over sed for simple string replacements.
  • Prefer [[ over test or [.
  • Prefer process substitution over a pipe in while read loops.
  • Use (( or let, not $(( when you don't need the result

Haskell

  • Avoid partial functions (head, read, etc).
  • Compile code with -Wall -Werror.

Ember

  • Avoid using $ without scoping to this.$ in views and components.
  • Prefer to make model lookup calls in routes instead of controllers (find, findAll, etc.).
  • Prefer adding properties to controllers instead of models.
  • Don't use jQuery outside of views and components.
  • Prefer to use predefined Ember.computed.* functions when possible.
  • Use href="#" for links that have an action.
  • Prefer dependency injection through Ember initializers over globals on window or namespaces.
  • Prefer sub-routes over maintaining state.

Testing

  • Prefer findWithAssert over find when fetching an element you expect to exist

Angular

  • Avoid manual dependency annotations. Disable mangling or use a pre-processor for annotations.
  • Prefer factory to service. If you desire a singleton, wrap the singleton class in a factory function and return a new instance of that class from the factory.
  • Prefer the translate directive to the translate filter for performance reasons.
  • Don't use the jQuery or $ global. Access jQuery via angular.element.
Something went wrong with that request. Please try again.