Best Practices

This document is to help each other with writing good structured code and have some kind of guide how to keep the code consistent throughout the whole project. The table of Content should give an idea which topics are dealt with.

Contribute

If you see something missing or something is unclear, change it. 👍

Table of Content

1. Project Structure Practices 🎨
2. Code Style Practices ☕️
3. Security Practices 🔒
4. Performance Practices 🏇

1. Project Structure Practices 🎨

We use a framework which has it's own folder structure. the default structure is something to hold on to make it easy to transits from learning Laravel to producing a real product.

1.1 Views

To keep the views structured, the views should be organized by function.

The views for the homepage have the function to inform the user and get them to use Statman, so it should be logic to add them to the folder frontpages. The same logic applies to the rest of the views. The name you use for the folder should always be plural.

/views
  /layouts
    master
    metadata
    navigation
    etc...
  /frontpages
    home
    about
    contact
    etc...
  /dashboards
    create-story
    etc...

File names are not CamelCase and are written with a dash; -

Example (Dash): add-service.blade.php

Example (CamelCase): addService.blade.php

1.2 Controllers

Controllers are at the core of the Laravel framework and make the base for our platform. To maintain consistentsies throughout the whole spectrum of controllers the name should reflect the action it fullfilles. Great examples are those within the auth folder.

Names like ResetPasswordController describe the action the controller will fulfill but keeps open the default function names with in the controller like; index, show, create, and store.

The names for the Controllers should be CamelCase.

Structure whise the folder Controllers should have child folders with names that discribes the component its used for.

/Controllers
  /Auth
    ForgetPasswordController
    LoginController
    etc...
  /Billing
    SendBillingController
    etc...
  /Admin
    RemoveUserController
    etc...

1.3 Models

Models make getting and saving data from the database easier by defining certain steps. The name should reflect the database table it will be talking through.

The names for the Models should be CamelCase.

1.4 Styling

The CSS or LESS files should be placed with in the assets folder within the public folder. To make the structure easy to remember just use the same structure as used with in the Views.

The file name is written without CamelCase and spaces should be filled with a dash; -

1.5 Javscript

The JS files should be in the assets folder within the public folder. The file name is written without CamelCase and spaces should be filled with a dash; -. Also for the JavaScript should the structure used with in the Views.

1.6 Images

The Images should be in the assets folder within the public folder. The file name is written without CamelCase and spaces should be filled with a dash; -

TL;DR

The above could be a bit overwhelming so to make it a little easy on you, a small recap.

Files:

File type	CamelCase	Dash
View	❌	✅
Controller	✅	❌
Model	✅	❌
Styling	❌	✅
Javascript	❌	✅
Image	❌	✅

Folders:

All folders should be plural.

Example: dashboards, frontpages , etc.

2. Code Style Practices ☕️

To keep the coding/programming style flush, the following practices are there so other developers know what you wrote and more readable.

2.1 Tabs of Indentation

Because of the immense discussion about 2 spaces vs 4 spaces we settle it here!

1 tab = 2 spaces

2.2 Curly Braces

The opening curly braces of a code block should be in the same line of the opening statement.

Code example

// Do
function someFunction() {
  // code block
}

// Avoid
function someFunction()
{
  // code block
}

If code is nested the closing curly braces should all be closing with out enters but with the correct spacing.

Code example

// Do
.class {
  // styling block

  &.class-two {
   // styling block

  }
}

// Avoid
.class
{
  // styling block
  &.class-two
  {
    // styling block
  }

}

2.3 Name Your Functions

All functions should have a descriptive name. it should reflect the action it will preform, this applies to JavaScript and Laravel. The names are written in camelCase(LowerCamelCase).

Code example

<?php

// Do
public function savePage() {
  // code block
}

// Avoid
public function SavePage() {
  // code block
}

2.4 Naming conventions for variables, constants, functions and classes

Use camelCase(LowerCamelCase) when naming variables and functions, CamelCase (capital first letter as well) when naming classes and UPPERCASE for constants. This will help you to easily distinguish between plain variables / functions, and classes that require instantiation. Use descriptive names, but try to keep them short.

Code example

// for class name we use UpperCamelCase
class SomeClassExample {

  // for const name we use UPPERCASE
  const CONFIG = {
    key: 'value'
  };

  // for variables and functions names we use lowerCamelCase
  let someVariableExample = 'value';
  function doSomething() {

  }
}

2.5 Front-end

The Front-end is coded with Less this is a precompiler for CSS. LESS is used for it's properties that you can read more about on there website. To make sure everybody is on the same page on how to structure the code here are some guides to help you out.

2.5.1 stylesheet structure

The stylesheet has it's own table of content to specify where certain styling should be placed.

//-----------------------------------
//              01. Mixins
//              02. Variable
//              03. Reset
//              04. Fonts
//              05. Base
//              06. Common classnames
//              07. Component's
//              08. Pages
//              09. Responsive
//-----------------------------------

The hierarchy with in the document is chosen this way to make it easy to overwrite exclusions on component's for certain pages or other devices.

To start a new chapter like 08. Pages make it big so people will notice:

//-----------------------------------
//              08. Pages
//-----------------------------------

When you work on the styling for a page, component or anything else start the styling block with // recent post and end it with // end recent post this makes the stylesheet more readable for other developers.

2.5.2 Classes & Id's

Styling should be done with a class not with Id's or an element. This is mainly for maintaining the code written, it could be that certain element like a H1 is changed to a H3 if the style is on the element the style is lost and extra code needs to be rewritten.

// Do
.title {
  font-size: 2.4rem;
}

// Avoid
h1 {
  font-size: 2.4rem;
}

The main function for an id is to be unique. This means it's great for selecting an element. an id should only be used for JavaScript. If JS is used it should reflect in the HTML it's used like that.

<!-- Do -->
<span id="js-trigger" class="trigger">I'm a Trigger!</span>

<!-- Avoid -->
<span id="trigger">I'm a Trigger!</span>

2.5.3 Naming Groups and items

Giving an descriptive name for a section or a div is one of those tasks that takes way to long. to make naming them easier a group is always example-group and an item is always example-item. to give you an idea what I mean:

<section class="features">

  <ul class="features-group">
    <li class="features-item">Some text</li>
    <li class="features-item">Some text</li>
    <li class="features-item">Some text</li>
  </ul>

</section>

This way you only need to worry about taking a hour to think of that purrfect name 😻 after you have done that everybody knows what to do next.

2.5.4 Styling structure

about now you are thinking "Really there are rules for styling structure...". Well yes there are. This is for you as a developer to make sure you don't define styling more times then absolutely necessary.

.styling {
  // 1. mixins and/or extends
  .displayflex();
  .clear;
  .animation(show);
  // 2. layout
  width: 100%;
  height: 100%;
  position: absolute;
  z-index: 1;
  right: 0;
  top: 0;
  float: left;
  margin: 0 0 0 0;
  padding: 0 0 0 0;
  text-align: center;
  // 3. color and background
  color: white;
  background: blue;
  // 4. fonts
  font-weight: bold;
  // 5. anything else
  user-select: none;
  transform: translateY(0) rotateZ(0);
}

there are many more styling properties but this should give you an idea how to structure the styling.

2.5.5 Modular

Always keep in mind "Will I use this Component some were else?" if the answer is Yes! Great make it Modular.

3. Security Practices 🔒

Always assume someone is going to break your app or that a function is not loading properly. The terms used for this is defensive programming.

To give some real life examples that are usefull:

3.1 define the input that should be expected

<?php
// Do
public function updatePassword(string $password) {
// some code
}

// Avoid
public function updatePassword($password) {
// some code
}

3.2 expect no data at all

<?php
// Do
@if ($message)
  <div class="message">{{ $message }}</div>
@endif

// Avoid
<div class="message">{{ $message }}</div>

The same rules apply for styling. for example Facebook didn't send an image for the post, load a default image.

3.3 Validation

check the laravel documentation for more information on validation: Validation

3.4 CSRF

check the laravel documentation for more information on CSRF tokens: Form anti-spoofing

3.5 TEST WHAT YOU WROTE!!

Most security issues are due to the developer being to lazy to go through there written code and check if they did a good job. check all input fields(form, url) and change value that are used to Identify a project or person. Don't be a sloppy boy 🐩

4. Performance Practices 🏇

Ask yourself: can it be smaller? if the answer is probably, then make it smaller or lighter.

4.1 Dimensions

There going to be icons, it's your job to send them back to the designer if they are to big. let's say you need an icon for the settings link. you style them to be purrrfectly 36px x 36px. if you remove the dimension styling is it going to be all over your page? probably yes. this means the dimensions are waaaayyyy too big! make sure the designer export the images in those dimensions.

4.2 Tools of the trade

Here are some tools to check performance and to optimize images.

• images
• SVG
• pagespeed
• Googlepagespeed
• CSSstats

PS: if you read the best practices add your name to the list:

• Max ✅
• Hans ✅
• Hendrik ✅