Code in Style

While everyone has his/her own preferences, working as a team - to build well-designed products - means agreeing on how the team will write clean, readable, and maintainable code. Some of these conventions might take some time for the team 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 of characters depends on 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, 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 needed columns (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 keywords and lowercase for SQL identifiers.

Non-relational Databases

• Avoid using it for every job. 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 offer SET and UPDATE operations that do not behave the same.

Code maintenance

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