Coding conventions

In code

Ekylibre projects are based on one idea at every level: Simplicity ⇒ Reliability ⇒ Adherence. Ekylibre follows a set of coding conventions:

General

  • All programming code must be in English as possible
  • No abbreviations
  • No ambiguities
  • Use meaningful names
  • Explain complex methods in a comment in code

Ruby/Rails

  • Follow Rails conventions:
    • Two spaces, no tabs (for indentation).
    • No trailing whitespace. Blank lines should not have any spaces.
    • Indent after private/protected.
    • Use Ruby ≥ 1.9 syntax for hashes. Prefer { a: :b } over { :a ⇒ :b }.
    • Prefer &&/|| over and/or.
    • Prefer class « self over self.method for class methods.
    • Use MyClass.my_method(my_arg) not my_method( my_arg ) or my_method my_arg.
    • Use a = b and not a=b.
    • Use assert_not methods instead of refute.
    • Prefer method { do_stuff } instead of method{do_stuff} for single-line blocks.
    • Follow the conventions in the source you see used already.
  • Avoid some keywords everywhere (alias, and, break, case, class, def, default, do, else, elsif, ensure, false, if, include, location, module, next, nil, not, or, redo, require, rescue, retry, return, self, super, then, true, type, undef, unless, until, when, while, and yield). Consequences are:
    • Type models are named as Nature models. Example: If you need to manage foo types, use FooNature instead of FooType.
    • Use by_default expression in replacement of default
  • Follow migration guidelines:
    • Never use models in migrations, because of their volatility. Only SQL.
    • Always ensure that a migration is reversible except in case of major version.
    • Reference column must be indexed
    • Reference column should have a foreign key constraint
    • Date columns name must be constructed as conjugated verb followed by _on suffix. Example: moved_on
    • Datetime columns name must be constructed as conjugated verb followed by _at suffix. Example: moved_at
    • Always add stamps columns in all tables you create.
    • For GIS DB columns, use only PostGIS columns: st_point in place of point and st_polygon in place of polygon
    • Every decimal rate column must be decimal(19,10)
    • All other decimal column must be decimal(19,4)
    • Every boolean column must be mandatory and false by default (null: false, default: false)

HTML

  • Use only dasherized style for tag name, attributes, IDs, and classes. Example: good-name is good, badName, BadName, bad_name are wrong.

CSS

  • Use only dasherized style for names. Example: good-name is good, badName, BadName, bad_name are wrong.

In version control system

  • Write explicit message in commit messages. These messages can be completed by action sentences for bug-trackers or project management tools. Example: “Adds color picker in activities. Fixes #534”
  • Every new feature must be developed in a new branch
  • Every new bugfix should be developed in a new branch

Pull requests management

  • The reviewer who merges a pull request is never the coder who wrote it.
  • The coder have to provide a branch up-to-date with master branch, else reviewer would ask for an update
  • The reviewer should review code as soon as possible to prevent de-synchronization with master branch
  • The reviewer must refuse a pull request unless:
    • Acceptance testing has been done
    • Code don't breaks these conventions
    • No test failure/error has been introduced compared to master branch
    • Code coverage percentage is greater than or equal to master branch's one
    • First-run task passes without hitch
    • Issue/PR on github is complete (comprehensive title/description - appropriate labels)
  • The reviewer have to report issues to the coder who works on pull request (in GitHub) if code is not acceptable.

Versioning

We follow the SemVer philosophy. Given a version number MAJOR.MINOR.PATCH, we increment the:

  1. MAJOR version when we add an irreversible migration
  2. MINOR version when we add new features without irreversible migrations
  3. PATCH version when we add only backwards-compatible bug fixes.

An irreversible migration is a migration which alters existing data without any reliable way to rollback changes at 100%. Most of the cases are:

  • Merging or deleting columns data (nomenclatures's, procedures's, enumerize's reference names…)
  • Merging or deleting columns of tables
  • Merging or deleting tables

To prevent frequent MAJOR releases, which is not a guarantee of stability, use of deprecation process is HIGHLY recommended when possible.