Skip to content

Latest commit

 

History

History
204 lines (158 loc) · 7.79 KB

README.md

File metadata and controls

204 lines (158 loc) · 7.79 KB

Coding standards

When contributing code to with me, you must follow its coding standards.

Globális irányelvek

  • verziószámozás esetében a Semantic Versioning követendő
  • EditorConfig használata javasolt
  • changelog (changelog.md) készítése javasolt a Keep a Changelog ajánlásai alapján
  • identre 4 space használata tabok helyett
  • UTF-8 kódolás használata
  • minden fájlnév kisbetűs, szavak elválasztására kötöjelet (-) kell használni
  • a kód dokumentálása történhet magyar vagy angol nyelven, viszont fontos, hogy konzekvens legyen

UX

Nyelvek megjelenítésére vonatkozó ajánlások többnyelvű oldalak esetén (további információ):

  • a felhasználó saját nyelvén legyen megjelenítve a nyelv (pl. german helyett deutsch)
  • lehetőség szerint az összes elérhető nyelvet jelenítsük meg
  • detektáljuk a felhasználó böngészőjének a nyelvét
  • ne használjunk zászlókat a nyelvek reprezentálására

Frontend Coding Standards

Frontend kódolási koncenciók

Alapvetések

  • projekt indulásnál a starter-kit használatos
  • törekedni kell a szemantikus kódra, a valid markup cél, de nem elvárás
  • kiemelt szempont a sebesség
  • elvárt a böngészőfüggetlen kód, ha arról a specifikáció másképp nem rendelkezik, akkor a támogatott böngészők az Internet Explorer 10+, illetve a Chrome és Firefox legfrisebb verziói
  • ha nem megoldható a böngészőfüggetlen kód, akkor törekedni kell az érintett böngészőben való használhatóságra
  • hibák jezése az alábbi útmutató alapján
  • megjegyzések írása a conventional comments alapján

HTML

  • kizárólag kisbetűket használunk
  • célszerű használni a HTML5 szemantikus új elemeit (header, footer, nav, article, section, stb...)

Példa: új komponens esetében használjuk a <section> vagy az <article> elemeket:

<section class="component">
  <h1 class="title">Title</h1>
  <p>Paragraph</p>
</section>
  • kizárólag HTML5 doctype használható (<!doctype html>)
  • kötelező az UTF-8 kódolást jelölő meta tag (<meta charset="UTF-8">), a kódolás megadásának az első 1024 byteban kell lennie
  • self closing elemeknél tilos kitenni a záró perjelet (<img src="/logo.png" alt="">)
  • attribútumok értékeinél double quotes használatos (") w3c
  • attribútumok sorrendje a codeguide szerint
  • entitásokat nem használunk, a kivételes eseteket leszámítva (< és >, illetve & némelyik speciális vezérlőkarakterhez, mint pl. a nem törhető szóközhöz)

CSS

  • kizárólag kisbetűket használunk
  • az egyes definíciók közé üres sor rakunk
  • minden deklaráció kerüljön új sorba
  • id- és osztályneveknél a szavak elválasztására kötőjelet használunk (.button-large)
  • a tulajdonságokat záró kettőspont utánt szóközt teszünk (font-weight: bold;)
  • url-ek megadásánál aposztrófot használunk (url('/image.png'))
  • preferáltan az osztályokat hasznájuk leginkább
  • ajánlott maximum 3 szint mélységig menni az osztályok specificity-jében
  • !important kulcsszó használata kerülendő
  • shorthand-ek felesleges használata kerülendő, pl. ne használjunk background shorthandet ha csak háttérszínt szeretnék módosítani
  • ha valahol elkerülhetetlen a CSS hack használata, akkor különítsül el egy shame.css-be
  • 0, mint érték megadása esetén a mértékegység megadása felesleges ezért kerülendő

Példa:

html {
    background: #fff;
}

.doc-block,
.post-meta {
    margin: auto;
    width: 50%;
}

.navbar {
  margin-bottom: var(--space);

  @media (min-width: 480px) {
    padding: 10px;
  }

  @media (min-width: 768px) {
    position: absolute;
    top: 0;
    left: 0;
  }

  @media (min-width: 992px) {
    position: fixed;
  }
}

JavaSrcipt

  • JS prefix használata ajánlott, ezek formázása CSS-el kerülendő
<div id="js-slider" class="my-slider">
  • kód dokumentálásához a JSDoc használandó

Assetek

  • képek fájlneveiben kötőjelet használunk (header-background.png)

PHP Coding Standards

PHP kódolási koncenciók.

  • változónevek kiválaszátáshoz a naming-cheatsheet-et ajánlott alkalmazni
  • PSR-1 és PSR-12 követése
  • sztringek esetében az aposztróf (') használata kötelező, változók esetében használható a double quote (")
$q = htmlentities($searchValue, ENT_QUOTES, 'UTF-8');
echo "<input type='search' name='q' placeholder='Search' value='$q'>";
  • Kommentek esetében a phpDocumentor előírásait kell követni
  • vezérlési szerkezeteknél használhatóak az alternatív verziók, mint például az endif és endforaech, de főleg templatekben

Short if használata (a váratlan eredmények elkerülése érdekében):

$error = ($error_status ? 'Error' : 'No Error');

Sztringek összefűzésénél:

$error = 'Status: ' . ($error_status ? 'Error' : 'No Error');
  • short tag-et lehet használni és nem szükséges a végére pontosvessző (forrás)
<?= $var ?>
  • osztály példányosításakor kirakjuk a zárójelet
$car = new Car();

Megjegyzések

  • sorvégek Unix LF formában
  • minden fájl végén legyen egy üres sor
  • a null, továbbá a true és false kisbetűvel

Eszközök

  • statikus kód analízis

Kiegészítések

  • short tag-ek használata tilos
  • kód kommentelése elvárt a szükséges mértékben
  • todo címkék használata lehetséges, de legyen felvive az Issue trackerbe

Laravel specifikus

Alapvetések

Frissítés

  • Adott projekt abban a verzióban tölti a teljes életciklusát, amelyben indult
  • Nagyobb és folyamatosan karbantartott projektek esetében Laravel Shift-el (vagy manuálisan) frissítünk

Git

feature
bugfix
task
wip

Példák:

git commit -m "feat: allow provided config object to extend configs"
git commit -m "docs: correct spelling of CHANGELOG"
git commit -m "feat(lang): add the Portuguese language"

Tartalom

  • ha a projekt költségvetés engedi, akkor érdemes szövegírót alkalmazni
  • ha az előbbira nincs lehetőség, akkor a közérthető fogalmazás alapelveit érdemes betartani

Ajánlott külső függvénykönyvtárak

Az ajánlott vendorok megtalálhatóak az awesome-links gyűjteményemben.

Hasznos linkek