Code best practise

Obecné

• Řádné odsazení. Nemíchat tabulátory a mezery. Správné odsazení jsou 4 mezery s vyjímkou CSS šablon a view - soubory s koncovkou pthml, kde se používají 2 mezery.

Pro toto lze využít IDE a předdefinovat domluvené nastavení. IDE samotné soubor uloží tak, že převede tabulátory na mezery.

• Správné pojmenování proměnných, tříd. Proměnné a členské atributy tříd vždy začínají vždy malým písmenem, třídy velkým.

Obecně by se mělo dodržovat CamelCase, viz PSR-1 a PSR-2. Znovu, stačí pouze preddefinovat PSR-2 standard v IDE.

• Guard conditions - omezení zanoření. Místo:

if ($this->valid()) {
    // normální zpracování
} else {
    throw new Exception();
}

použít:

if (! $this->valid()) {
    throw new Exception();
}
// normální zpracování

Šablony

• Šablony slouží pro zobrazení dat, komplikovaná logika by se měla řešit mimo ně (v controlleru či record driveru či jiném vhodném místě).
• Používat short tags v PHP místo echo:

<a href="/Record/<?=$this->driver->getUniqueID()?>" class="title">

• Vhodně escapovat výstup v šablonách

• Nepsat inline CSS, ale využívat LESS, proměnné a zanořování

• Nepsat vlastní pravidla ale využívat předdefinované třídy (Viz Bootstrap 4, a jeho Utilities https://getbootstrap.com/docs/4.0/utilities/clearfix/)

• Při psaní CSS využívat BEM (block-element-modifier), viz http://getbem.com/introduction/

JavaScript

• Pokud možno NEpoužívat knihovnu jQuery. Knihovna je extrémně pomalá. Standardní JavaScript pracuje s DOMem 34x rychleji. Každou chvíli jsou funkce jQuery deprecated, viz $.ajax callbacks. jQuery je pak potřeba přepisovat.
• Využívat standardní funkcionalitu nejnovějšího EcmaScriptu (momentálně ES8 neboli ES2017)
• Využívat zkrácenou arrow syntax

Místo

let materials = [
  'Hydrogen',
  'Helium',
  'Lithium',
  'Beryllium'
];

materials.map(function(material) { 
  return material.length; 
}); // [8, 6, 7, 9]

psát

materials.map(({length}) => length); // [8, 6, 7, 9]

• Místo ES5 callbacků využívat promisy, async/await
• Nepoužívat var, ale let a const (pokud někdo v kódu narazí na var, přepsat)
• Používat EsLint
• Javascript psát jenom do samostatných souborů. Tyto soubory paj lze minifikovat do produkce.
• Soubory dělit do modulů a ty pak importovat,

export default class {}

import CpkNavigation from './components/CpkNavigation.vue';

• Využívat výhody TypeScriptu

  • plně Objektově orientované programování
  • dedičnost - a psát tak znovupoužitelný kód
  • typovou kontrolu - a předejít chybám

• Nevynalézat znovu kolo a využívat existující kód viz npm (node_modules) Tyto knihovny stačí minifikovaně importovat a rovnou využívat.

• Kód by měl před deployem projít kompilací (například Babelem https://babeljs.io/), který veškerý JavaScript (jakékoliv verze) překompiluje do standardního JS, kterému rozumí všechny prhlížeče od IE8, čímž lze využívat všechny funkce napříc prohlžeči a zachovat tak kompatibilu. U tohoto řešení zcela odpadá nutnost importovat různe další knihovny pro podporu IE, promisů atd. Ušetří se místo, paměť, kód je kompatibilní, web je rychlejší, stabilnější, Angular 1 funguje.. Babel lze spouštět pomocí Webpacku, Eventuelně lze použít http://browserify.org/

Instalace

npm install -g browserify

Automatické Použití v Dockeru

browserify main.js -o bundle.js

Použití

<script src="bundle.js"></script>

Lze nastavit, aby se u minifikace zachovali plné názvy funkcí. Lze také využít již použité Sentry. Minimální snaha, maximální účinek.

• Pokud možno přepsat asynchornní dotahování výsledků vyhledávání tak, aby se nedotahovali již vygenerované celé šablony, ale aby se použil HTML5 template, kterému stačí dotahovat jenom data pomocí JSONu.

Příkad

<template>
    <div>
        <div class="row">
            <div class="col-md-12">
                <record></record>
            </div>
        </div>
    </div>
</template>

• Odstranit Angular, nebo ho naopak plně využít (raději ale odstranit, jelikož není podporován a když použít frontend framework, tak nahradit jiným aktuálním, s doboru podporou, Vue 2 nebo React (u tohoto řešení by odpadla nutnost handlovat historii prohlížeče)) O výhodách použití frontend frameworku není nutno diskutovat, avšak první kroky by měli být výše zmíněné body.

• nevymýšlet vlastní konstukce ale využívat nativní funkce a built-in konstrukce jazyka, viz FOR OF

for (let n of fibonacci) {
    if (n > 1000)
        break
    console.log(n)
}

• nepsát foreache když lze použít oneliner, např funkci map()

materials.map(({length}) => length); // [8, 6, 7, 9]

• Destructuring Assignment Místo

let tmp = getASTNode();
let op  = tmp.op;
let lhs = tmp.lhs;
let rhs = tmp.rhs;

lze použít objektovou destukci

let { op, lhs, rhs } = getASTNode()

Tato vlastnost jazyka umožnuje zbavit se zastaralých způsobů psaní boilerplatů Viz špatný kód, který vůbec nic nedělá a lze ho bez obav smazat. https://github.com/moravianlibrary/CPK/commit/ca01bea0a67103769169f8793af8595f50ddf6cb#diff-45799b071d3482369964d0b12f647064R228

Řádky 74-250

• Enhanced Object Properties

Místo

obj = { x: x, y: y };

lze napsat

obj = { x, y }

• String Interpolation

Nekombinovat text, proměnné, HTML a funkce dohromady.

let message = "Hello " + customer.name + ",\n";

Ale využít Template Literals

let message = `Hello ${customer.name}`

To samé lze využit pro velké konstukce s HTML5 elementem template.

• Předdefinvoat hodnoty funkce touto syntaxí

function f (x, y = 7, z = 42) {
    return x + y + z
}

a ne

function f (x, y, z) {
    if (y === undefined)
        y = 7;
    if (z === undefined)
        z = 42;
    return x + y + z;
};

• Uklízet po sobě a odstranovat redundantní dumpy console.log()

Poznámky

• Že je web napsaný v JavaScriptu již dnes neznamení, že je neviditelný pro boty
• Nejlepší, co lze pro vývoj frontendu doporučit je Webpack, viz https://webpack.js.org/
• Poznáka k var, let, const. Const by mělo znamenat, že je tato "proměnná" immutable. To znamená, že nelze provést reassignement. Avšak je-li to například Array, lze provést push() a tím tuto "konstantu" změnit. Takže použití const je diskutabilní a na Internetu se vedou nekonečné diskuse.

Já však doporučuji const používat minimálně pro variables, které by neměli být mutable, například takto:

const ExtractTextPlugin = require("extract-text-webpack-plugin");

-- Toto bych samozřejmě psal v ES6,7,8 jinak

import ExtractTextPlugin from 'extract-text-webpack-plugin';

avšak jsou případy jako tento, kdy je potřebovat použít zastaralou JS syntax (require místo import), který ješte neprošel a ani neprojde kompilátorem do VanillaJS (Babel). Konkrétně by šlo o Javascript který by inicializoval samotnou kompilaci.

O JavaScriptu lze hodne diskutovat a napsat, avšak toto lze považovat za konečné doporučení pro začátek roku 2018.