Code in Style

While everyone has his/her own preferences, working as a team - to build well designed products - means to agree on how we will write clean, readable and maintainable code. Some of these conventions might take some time for you to get used to but they are not to be blindly followed; strive to understand these and ask when in doubt.

General Best Practices

• 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.

Formatting

• Break long lines of code. The number fo characters depends from each stack.
• Place comments above the concerned line(s). Do not inline comments.
• Don’t misspell.
• Use an empty line between methods.
• Use spaces after commas, after colons and semicolons, around { and before }.
• Use Unix-style line endings (\n).

Naming

• Avoid abbreviations.
• Use American English 🇺🇸.
• Name variables, methods, and classes to reveal intent.
• Prefer the singular of a word over its plural version.
• Avoid object types in names e.g. user_array, email_method, CalculatorClass, ReportModule.
• Prefer naming classes after domain concepts rather than patterns they implement e.g. Guest vs NullUser, CachedRequest vs RequestDecorator.
• Suffix variables holding a type with their _type e.g. user_factory, user_spec.

• Treat acronyms as words in names, even if the acronym is the entire name.

  XMLHTTPRequest = '';
  class HTML
  end
  

  XmlHttpRequest = '';
    
  class Html
  end
  

Organization

• Order methods so that caller methods are earlier in the file than the methods they call.
• Order methods so that methods are as close as possible to other methods they call.

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.

Relational Databases

• Index foreign keys.
• Constrain most columns as NOT NULL.
• In a SQL statement, only select columns you need (i.e., avoid SELECT table.*).
• Use an ORDER BY clause on queries where the results will be displayed to a user, as queries without one may return results in a changing, arbitrary order.
• Use uppercase for SQL key words and lowercase for SQL identifiers.

Non-relational Databases

• Do not try to make it do every job you have. For transaction-based applications with fixed entities, relational databases are better suited.
• Avoid deep nesting of data. Instead, data should be de-normalized/flattened as much as possible.
• Beware of update operations. Most databases offers SET and UPDATE operations that do not behave the same.

API Design

• We generally follow REST and JSON API. In addition, before designing a new API, review the recommended practices outlined in Heroku API Design Guide.
• Version endpoints e.g. v1/, v2.
• Document the endpoints and parameters. Online tools like Apiary or API Docs can be used.

Code maintenance

• Use TODO to mark incomplete parts of code.
• Use FIXME to mark parts of code that are broken or cause bugs.