# Guides & principles
These guides and principles are meant to help you in your development process. They are, however, not set in stone. If you think of a better guideline or principles please let the team know.

<!-- <a id="whats-new"></a>
#  What's new -->

<a id="directory-structure"></a>
#  Directory structure
To keep our code structured and easier to index we keep a similar file structure in all our projects. Some of the assets will come from `matise-assets`
This is our file structure for Nuxt projects, which is mostly decided by the way Nuxt is set up:

```
assets
--| fonts // all fonts used in the website
--| icons // if vue-svgicon is used
--| images
--| scss
-----| color
--------| _default.scss // example of file name
--------| _index.scss // example of file name
--------| _case-colors.scss // example of file name
-----| components
-----| icons
-----| layout
-----| mixins
-----| settings
-----| typography
-----| app.scss
--| svg-icons // if vue-svgicon is used
components
layouts
pages
--| pages
-----| subpages
```

It's important that all scss files inside of a map are included **once** in the `_index.scss` for example in `color/_index.scss`:
``` css
@import 'default', 'case-colors';
```
The index scss files contain only imports, and are then included in `app.scss`.
``` css
@import 'color/index', '~matise-stack/_stack.scss', '~matise-grid/grid.scss', 'settings/index', 'mixins/index', 'typography/index', 'layout/index', 'components/index', 'icons/icons';

```
We're also including `matise-stack` and `matise-grid` in `app.scss`.

<a id="code-conventions"></a>
#  Code conventions
Code conventions help teams be more productive, code should be read as if it was written by just one person even if 5 people worked on the project.


<a id="html"></a>
#  HTML
#### Common sense HTML
Syntactically correct HTML is an important base for any website. It makes HTML easier to read, and helps all sort of machines give meaning to your code.

- We use semantically correct HTML5 elements where possible.
- Empty elements are on a single line.
- We use 1 tab for indentation.
- We use aria-labels to convey meaning to screenreaders on elements that are triggered only by javascript.
- We use a language element in all our websites, since this is essential for people using screenreaders and improves SEO.
- Attribute values get double quotes.
- We always add an alt tag to images to improve accessibility, unless the image conveys no real meaning, then it's better to leave the alt tag empty.
- We don't use spaces around the equals sign of properties, to improve readability; `rel='stylesheet'` not `rel = 'stylesheet'`.


 <a id="scss"></a>
# SCSS
#### Common sense SCSS
* 1 tab for indentation.
* Use the BEM naming convention.
* Find elegant solutions for focus styles without disabling them.
* Don't rely on prefixes, these are declarations that can still change in functionality and are not finished.
* Don't write out prefixes, use [Autoprefixer](https://github.com/postcss/autoprefixer) if you must.
* Avoid ID's and unnecessary specificity in selectors #aintnobodygottimeforthat
* Maximum nesting: three levels deep. (for readability, and reusability)
* List Vendor/Global Dependencies First, Then Author Dependencies, Then Patterns, Then Parts
* Break Into As Many Small Files As Makes Sense
* Partials are named `_partial.scss`
* Be Generous With Comments
* Variablize All Colors
* Use z-index **sensibly**, `z-index: 999;` == ☠️

#### Order of styles
1. `@extends`
2. `@includes`
3. Regular styles
4. Nested pseudo classes & -elements
5. Nested selectors

```css
.title{
  @extend %h1;
  @include transform(rotate(90deg));
  background: color(MatiseBlack);
  &:hover{
    background: color(MatiseBlack);
  }
  &::before{
   content: "";
   display: flex;
  }
  > h3{
   @include transform(rotate(90deg));
   border-bottom: 1px solid white;
  }
 }
```

#### Naming convention
We use the BEM method of naming elements, BEM stands for Block Element Modify.

```css
/* Block component */
.btn{}

/* Element that depends upon the block */
.btn__price{}

/* Modifier that changes the style of the block */
.btn--orange{}
.btn--big{}
```
>In this CSS methodology a block is a top-level abstraction of a new component, for example a button: .btn { }. This block should be thought of as a parent. Child items, or elements, can be placed inside and these are denoted by two underscores following the name of the block like .btn__price { }. Finally, modifiers can manipulate the block so that we can theme or style that particular component without inflicting changes on a completely unrelated module. This is done by appending two hyphens to the name of the block just like btn--orange.

Source: [BEM101](https://css-tricks.com/bem-101/)

```html
<a class="btn btn--big btn--orange" href="http://css-tricks.com">
  <span class="btn__price">$9.99</span>
  <span class="btn__text">Subscribe</span>
</a>
```
>If another developer wrote this markup, and we weren't familiar with the CSS, we should still have a good idea of which classes are responsible for what and how they depend on one another. Developers can then build their own components and modify the existing block to their heart's content. Without writing much CSS, developers are potentially capable of creating many different combinations of buttons simply by changing a class in the markup.

Source: [BEM101](https://css-tricks.com/bem-101/)

An example of how we would use it in on a `nav`:
```html
<nav class="nav">
  <div class="nav__mobile-control nav__mobile-control--closed">+</div>
  <ul class="nav__list">
    <li class="nav__item nav__item--active">About</li>
    <li class="nav__item">Work</li>
    <li class="nav__item">Contact</li>
  </ul>
</nav>
```

```css
.nav{
 &__mobile-control{
  width: rem(20); height: rem(20);
  background: black; color: white;
  display: flex; justify-content: center; align-content: center;
  &--closed{
    transform: rotate(45deg); transition: 1s;
  }
  &--open{
    transform: rotate(0); transition: 1s;
  }
 }
 &__list{
  padding: 0;
  display: flex; justify-content: space-between;
  width: rem(300);
 }
 &__item{
  display: inline-flex;
  font-family: Roboto; font-size: rem(16);
  list-style-type: none;
  &--active{
   color: teal;
  }
 }
}
```
#### TLDR;
```html
<section class="block">
  <div class="block__element"></div>
  <div class="block__element block__element--modifier"></div>
</section>
```

```css
.block{
	/* Container */
	&__element{
		/* Signifies the element that is inside a block. */
		&--modifier{
			/* Signifies an exception to a style, like color, or signifies a state of the element. */
		}
	}
}
```

#### How we write
When we write SCSS we try to group CSS declarations by subject; width & height of an element, display settings of an element, etc.
For readability we write matching declarations on a single line. The curly bracket after the selector is **not** preceded by a space but is followed by a line-break, the closing curly bracket is on a new line. The
```css
.world{
  &__domination{
    width: rem(30); height: rem(30);
    background: url('https://tinyurl.com/y9t2l4f7') no-repeat; background-size: cover;
    display: flex; justify-content: center; flex-direction: column;
  }
}
```

<a id="javascript"></a>
#  JavaScript
#### Common sense JavaScript
* 1 tab – for indentation.
* Single quotes for strings – except to avoid escaping.
* No unused variables.
* Use semicolons.
* Always use `===` instead of `==` – but `obj == null` is allowed to check `null || undefined`.
* Be Generous With Comments

#### Naming
Use camelCase for variable- and function names.
```javascript
  var codeConvention = 'camelCasing';
  var matise = 'Happy coding!';
```

#### Spaces
Use spaces around operators; `= + - * / ` and **after** commas. Put spaces after keywords and function names.
```javascript
  var x = (2 / 5) * 10;
  if (worldDomination) {
   // domination plan
  }
  function matise (world, domination) {
   // the world is ours
  }
```

#### Indentation
We always use a single tab for code indentation.

#### Statements
We end simple statements with a semicolon.
``` javascript
var matise = ['mokerdik', 'world domination'];
var matiseInfo = {
  occupation: 'zieke hacker',
  goal: 'world domination'
};
```
We handle complex statements like this:
* Put the opening bracket at the end of the first line.
* Use one space before the opening bracket.
* Put the closing bracket on a new line, without leading spaces.
* Do not end a complex statement with a semicolon.

```javascript
function worldDomination () {
  // be complicated
}
if (worldDomination === 'succes') {
  // we rule the world
} else {
  // try again
}
```

To help us along we use an ESLint file, add this as `.eslintrc.js` to the root of your project:
```javascript
module.exports = {
	"root": true,
	"env": {
		"browser": true,
		"es6": true,
		"node": true
	},
	"extends": [
		"eslint:recommended",
		"plugin:vue/recommended",
	],
	"parserOptions": {
		"parser": 'babel-eslint'
	},
	"plugins": [
		'vue'
	],
	"rules": {
		"no-console": [
			"off",
			"allow"
		],
		"no-unused-vars": [
			"warn", {
				"properties": "always"
			}
		],
		"vue/html-indent": [
			"warn",
			"tab",
			{
				"alignAttributesVertically": true
			}
		],
		"vue/max-attributes-per-line": [0, {
			"singleline": 5,
			"multiline": {
				"max": 5,
				"allowFirstLine": false
			}
		}],
		"vue/require-v-for-key": "off",
		"vue/no-confusing-v-for-v-if": "off",
		"vue/require-prop-types": "off",
		"vue/attributes-order": "off",
		"vue/html-self-closing": "off",
		"no-unused-labels": "off",
		"indent": [
			"warn",
			"tab"
		],
		"linebreak-style": [
			"warn", "unix"
		],
		"quotes": [
			"warn",
			"single"
		],
		"semi": [
			"warn",
			"always"
		],
		"camelcase": [
			"warn", {
				"properties": "always"
			}
		],
	}
};

```

<a id="accessibility"></a>
# Accessibility
Accessibility is an important part of our development process. We work with a standard set of assets in which `:focus` styles, inputs and form validation are delicately designed and implemented. If you decide to change these styles please take into consideration what your action might mean to a user with a disability.

Making a website more accessible is not only good for inclusivity but also for SEO and users who aren't disabled.

Here are some golden rules to keep in mind while developing:
- Use semantic HTML5 tags.
- Use descriptive link texts, [click here](https://theannoyingsite.com) is **not** done.
- If possible supply text alternatives to time-based media (like video's and audio).
- Do not use `:before` or `:after` to add important texts to elements, this will not be visible to screenreaders.
- Make elements distinguishable, and use enough [contrast](http://contrast-ratio.com/).
- Make elements that look the same, act the same.
- Think about the implications of movement on or next to text for people who struggle with their attention span.
- Give users clear instructions and show them what they're doing wrong when an error occurs.


<a id="github"></a>
# GitHub

#### Read me
In every repository we write a `readme.md` that contains the following:
* Install instructions
* Small description of project
* Feature possibilities/wish list

[Markdown tips](https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet)

#### Feature branches
We work in feature branches to keep the `develop` and `master` branch free from questionable code.

![feature branch](https://www.atlassian.com/dam/jcr:746be214-eb99-462c-9319-04a4d2eeebfa/01.svg)

Source: [Atlassian](https://www.atlassian.com/dam/jcr:746be214-eb99-462c-9319-04a4d2eeebfa/01.svg)

#### How:
On the `develop` branch start a new feature branch, the syntax for a feature branch is `feature/{featurename}`

```
$git checkout -b feature/disco
$git push
```
It might produce this error:
```
fatal: The current branch feature/disco has no upstream branch.
To push the current branch and set the remote as upstream, use

git push --set-upstream origin feature/disco
```
Use the command that is suggested and you can use git push without having to type `origin feature/disco` everytime :).


When a feature is **100%** finished and tested for bugs you can make a pull request to the `develop` branch.
Go to the GitHub repository in your browser and make a new pull request.

Make sure you compare the `develop` branch with the feature branch you want to merge. If your branch is ✅able to merge automatically, write a good commit message and click 'Create pull request'. Github will check again if there are no conflicts between the branches and will show 'Merge pull request' if it's done. Click and confirm the merge, and delete the feature branch.

If your feature branch has a conflict with the `develop` branch solve the conflict and merge them. If you're not sure about the conflict assign team members to look at it to and click 'Create pull request'. After you've checked and fixed all your conflicts; click and confirm the merge, and delete the feature branch.


#### TLDR;
* Work in feature branches.
* Start a feature branch with feature/...
* Only make a pull request when a feature is 100% finished
* Once you've merched the pull request delete the feature branch

## Committing
#### Why
Committing usually starts of pretty seriously in a project but ends up happening less frequently and with exponentially more ridiculous commit messages.
Especially when you want to see where a bug came from it's important to use good commit messages.

#### When
>You commit when you have reached a codebase state you want to remember. There are a lot of reasons why you might want to remember a particular codebase state, so there can't be hard-and-fast rules on when to commit. However, number of commits is definitely not a measure of quality or progress. Source: [Stack exchange question](https://softwareengineering.stackexchange.com/questions/83837/when-to-commit-code)

I would also recommend committing after finishing an element or before you go home.

#### How
* GitHub recommends keeping your commit messages below the 50 character limit. It can be longer than 50 characters, but it's not recommended due to readability. It is possible to enter a description of your commit, but that's not an easy task using the CLI.
* Capitalize every commit.
* Do not use a period (.) at the end of a commit message.
* Use the [imperative mood](#imperative-mood) in the subject line.

<a id="imperative-mood"></a>
#### Imperative mood
>Imperative mood just means “spoken or written as if giving a command or instruction”.

* `$ git commit -m "Style the header"`
* `$ git commit -m "Make animation for the subnavigation"`
* `$ git commit -m "Update read me with GitHub guidelines"`

>[...]
The imperative can sound a little rude; that’s why we don’t often use it. But it’s perfect for Git commit subject lines. One reason for this is that Git itself uses the imperative whenever it creates a commit on your behalf. Source: [Chris Beams](https://chris.beams.io/posts/git-commit/)