IxDF Developer Docs

Appearance

Coding principles ​

These principles don’t include well-known principles like KISS, DRY, SOLID, YAGNI, etc: we assume that you already follow them. In this document, we focus on something that’s applicable to our codebase but can be too opinionated on other projects.

What’s the "status" of the codebase right now? ​

"If everything’s under control, you’re going too slow!" ― Mario Andretti

There is always something to improve, and that’s OK!

There will always be a lot of old code that does not follow our new conventions and quality standards (when it’s not easy to automate the fix of the issue); that’s also sort of OK. Our goal as developers is to constantly improve our codebase and apply our high-quality standards to NEW code, AND occasionally to OLD code.

Principles ​

1. Prefer evergreen ​

As a long-living project, we want to use long-living tools (packages, libs, frameworks) (nobody wants to use BackboneJS + CoffeeScript nowadays, right?). This is why we have as first principle: #usetheplatform. It means use native features the platform provides: modern browsers/EcmaScript, avoid any exotic PHP modules/extensions or rare tools without support. Some examples (bad -> good):

  • Less/Sass -> PostCSS (env preset)
  • Lodash.js -> ES6+/Babel (stage 2+ features)
  • React -> Web Components (+ wrappers)
  • Axios -> Fetch API (+ wrappers)
  • *some Laravel package -> Native Laravel functionality + few lines of extra code

From our experience, it’s better to wrap native browser’s APIs and use our wrappers instead. It allows us to have a single point of change.

This principle also means to use tools as they are intended to be used: if you use Laravel – use it in Laravel way.

2. Readable code > docs ​

Next principle is PREFER READABLE CODE OVER VERBOSE DOCS.

In practice, that means you should add comments only when it’s not possible to express your ideas by code: new variables, new functions.

For these reasons, we prefer to use native PHP types over PHPDoc blocks (the second reason is to help static-analyzers to inspect code). A good example of when it’s better to have docs: hacks, long DB queries, domain rules.

In a lot of cases, git history can tell you why any line of code added/changed (this is why it’s important to write good git commit messages with a link to the GitHub issue).

Materials: Document the weird.

3. No magic ​

Last but not least: NO MAGIC. Both languages we use (PHP and JS) allow developers to write magic code that’s difficult to inspect by static-analyzers (ESLint, Psalm, IDEs, etc.).

At the same time, these languages (more or less) allow writing inspect-able code. We prefer to delegate code-inspections to machines and trust them.