The coding standards for developers at Bytecode Digital Agency B.V. to ensure code health and quality of the products delivered to our clients.

Please use these standards in every line of code you write. This is not to bully you but to make sure everyone in our company writes code the same way, and this is the only way to assure quality of our code.

This repo also contains files you can use for development. These files are defaults, so you can of course edit them to suit the needs of the project.

Please read this file thoroughly, and also check out the links in the Final words section. Spending half an hour now can save you many hours during projects!

Remark: This project also includes our Parcel starter

We will discuss the following points in this Coding Standards file:

• General
• General Style
• Security
• Git
• HTML
• CSS
• CSS-preprocessors
• Javascript
• PHP
• WordPress

These are the general rules we use for writing software.

• Write clean code!
• Structure your work in a way that other developers can easily understand it. This means having the possibility of co-workers modifying your code in the back of your mind
• Document your code for end users, and when writing small and general functions
• DRY: Don't repeat yourself! Don't build long functions that do a specific thing, but try to create smaller and more general functions
• Write SOLID code
• When writing a part of a project that is essential to other systems, write unit tests to make sure these systems can depend on your code
• When starting on a project, try to pick the best tool for the job. Be sure to discuss this with your superior, as this can have a lot of impact on a project
• Use a clean folder structure. There is no default folder structure, because this depends on the kind of product. Just to be sure your colleagues can work with your code, discuss your proposal for the project folder structure with your superior
• Write your code with the latest techniques, and let tools like Babel or PostCSS take care of backwards compatibility
• For production, uglify/minify your code and remove source maps
• All communication on GitLab and all documentation (and everything else in Git repos) should be in English

• Don't use "Yoda" conditions, as these make it harder to read your code at a glance
• Use camelCase and use single quotes (unless the language does not allow this). This is mostly taken care of by our linters
• Indent using 4 spaces. This implies that tab characters should not be used for indentation. Set your code editor to convert tabs to 4 spaces.
• Opening curly braces should be placed on the same line as the method declaration, like function test() {, not on a separate line
• Lines should be at most 80 characters (spaces included). This is also taken care of by our linters
• For single line comments, use // comment, for multi-line comments, use /** * comment */
• Make sure your code is readable. This means using clear names for your functions, adding enough (although not too many) comments and adding enough and a consistent amount of whitespace. The latter is mostly taken care of by our linters.
• On that subject: use linters, and let the linter check your code before committing on Git. You can also use git-hooks to lint your code as you commit
• Leave an empty last line in every file
• If the project allows it, unit and integration tests are highly appreciated
• If possible, behaviour-driven development and test-driven development approaches are encouraged

• For security reasons try to avoid using FTP, rather use SFTP or connect through SSH and pull from the Git repo (with a deploy key)
• When using SSH, if possible, use an SSH-key and not just a password. This is to improve security
• For deployment using Git, or when setting up Git on a remote server, always use deploy keys, and do not reuse these keys
• When you add any login credentials or keys in a Git repo, even if it's a private repo with limited access, encrypt the files containing the credentials/keys if possible for maximum security
• Make use of (gitignored) .env files to keep environment variables secret, and easy to setup between environments

• GitLab should be used as main Git server, if needed GitHub can be setup as repository mirror
• Don't merge your own code into the develop/master branch, always create a pull request and let at least one other developer review the code
• Work on your own branch and name the branch to your first name. If a GitLab Board is used for the project, you can name the branch after the issue name in a GitLab Board
• Make sure you always add steps in the README.md file for others to make your code run: include the needed global dependencies, commands to install dependencies, and steps to run everything.
• Git README.md badges are sexy. Add them! For examples, check the top of this repo
• To make sure your project will run on the computer of others, use tools like TravisCI, CircleCI or Jenkins
• If your project uses a set of dependencies (like Mongo and Node) working together in a complex way, write a Dockerfile or Docker Compose file
• Write a clear description for your commit which makes clear what was changed or added, fo example: not "styling updates", but rather "improved styling for the menu dropdown"
• Before pushing, see if you are pushing the right files and you are not uploading confidential files or files that should not be in the Git repository
• If your commit is to fix a GitLab issue, include the issue number in your commit message, so your commit/branch will be linked to the correct issue
• Try to commit at least around every hour or two or after important milestones
• Use semantic versioning for production releases

• To ensure compatibility between local, development, staging, test and production environments, the use of Docker is encouraged
• Docker Compose should be used when there are multiple services running, like PHP and MySQL
• Using Docker Compose for just one container is still encourtaged
• Always prefer 2 smaller containers over 1 larger one
• For running services in production, Docker Compose is prefered over systemd, init.d, etc.
• If Nginx is used (as a reverse proxy), Nginx should be run through Docker Compose
• Usage of Linux Alpine is prefered, because it is a very light distro and will speed things up a lot
• The docker-compose.yml file should be the same between environments, so no -prod.yml, -dev.yml files
• GitLab can be used as container repository

• Use external files to include styling and scripts (never use in-line styling).
• Use <link rel="stylesheet" href="proxy.php?url=https%3A%2F%2Fgithub.com%2Fstyle.css"> and not @import to add styling. For scripts use <script src="proxy.php?url=https%3A%2F%2Fgithub.com%2Fcodeguide.js" />
• For your own code, you can include just 1 script file and 1 stylesheet, so combine everything using tools like Gulp, Parcel or Webpack
• Add an alt tag to images
• Use double quotes like <a href="proxy.php?url=https%3A%2F%2Fgithub.com%2F%23">, not single quotes like <a href='#'>
• Write your code with XHTML in mind, so use <br/> and not just <br>, because there is always a chance your code will later be converted into a React app. Side Note: using <br> in your HTML is not very semantic, use CSS for white space please 👼
• Make us of the HTML5 elements <article>, <nav>, <aside>, <details>, <header>, <footer>, <section>, instead of <div> where appropriate.
• Only leave an empty line between parts of the page, like the navigation, or <section> tags
• For templating, you can always use Handlebars. If you like to use another templating engine like, like Pug or ejs, discuss this with your superior
• Use the following order of attributes on HTML-elements:
  1. src, for, type, href, value
  2. id, name
  3. class
  4. data-*
  5. title, alt
  6. role, aria-*
• Use the following "basic" structure for HTML documents

<!DOCTYPE html>
<html lang="nl">
  <head>
    <meta charset="UTF-8">
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <meta http-equiv="X-UA-Compatible" content="ie=edge">
    <meta name="description" content="tekst">
    <meta name="keywords" content="tekst">
    <title>Document</title>
    [css dependencies]
    [font dependencies]
  </head>
  <body>
  Content goes here
  [javascript dependencies]
  </body>
</html>

• Try not to use CSS, rather use SASS/SCSS
• We strive to use as few CSS frameworks as possible. So only include a CSS framework/library after discussing
• If you are using Bootstrap (try not to use the whole framework, just the grid system), you can use Bootstrap 4, not Bootstrap 3, only if you have to work with legacy code that already includes Bootstrap 3
• If you are using another framework that uses px-units, use px, else use rem-values (rem values scale with the HTML-object's font-size, which makes responsive typography a whole lot easier)
• If the used frameworks allow it, write your media queries mobile first, like @media (min-width: 30rem)
• List related items together
• If a :hover pseudo class is styled, style :focus the same for accessibility
• Never use IDs, use classes
• Use BEM for naming CSS classes
• Name classes descriptively
• Use double quotes, not single quotes
• Use only one declaration per line, this makes the code more readable
• Add a space after the colon of a declaration, so not margin:1rem; but margin: 1rem;
• For font-sizes, use an exponential scale, preferably based on the Fibonacci number (1.618) Click here to geek out. There is also a Sass plugin available for modular scales like this. You can find the plugin here
• For colors, use hex values (not rgb or rgba), as short as possible, and in lowercase, for example: not #FFFFFF but #fff, and not background-color: #fff but background: #fff
• A zero (0) should not have unit
• Try to work with floats as little as possible, rather use flexbox or CSS grids
• If you are writing emails, use of the MJML preprocessor is encouraged

• Currently, SCSS is preferred for a project. If you want to use something else, discuss this with your superior
• Do not use extends, but use mixins
• Make use of the functionalities the preprocessor gives you! Don't do stuff yourself that a preprocessor can take care off for you
• You can compile your code to CSS using toolkits like Webpack or Gulp, although currently Parcel Bundler is the prefered method
• Don't go and add prefixes by hand. Instead, let a plugin handle this for you
• Try to avoid nesting, rather use BEM. Use of nesting is mostly resticted to :hover-states etc.
• When you do nest, make it at most 3 levels deep
• Provide the media queries rules inside the element
• Break files out into small modules (avoid having a file that is larger than 100 lines)
• Avoid using IDs throughout the site. Use IDs for parent elements. Example: Header, Footer, Main. Using Classes avoids having to use !important
• For shameful code, use the _shame.scss file. We all have to do this sometimes, better own up to it. More Geeky links
• Use the folder structure as given in this project

• If possible, use vanilla Javascript. Don't add jQuery just for a simple DOM manipulation or a simple API call
• Use Yarn as a package manager: it's better than NPM
• The usage of Typescript is encouraged to ensure type safety
• For linting, use ESLint (eslintrc is included in this repository). You're encouraged to use modules on top of ESLint like Prettier
• Write your code in ESNext/ES6+, and transpile using Babel to ES5 because Internet Explorer 😔
• Before adding a library, discuss with your superior
• Don't use anonymous functions (function test() {}), write them like this: const test = () => {}
• When using jQuery, write it using $('selector'); and not using jQuery('selector');, except when it gives compatiblity issues
• Comment your code following the ESDoc notation, it's understood by (almost) every code editor and IDE

• For server side stuff we prefer using NodeJS/Python over PHP, so only use PHP when necessary
• Use a clean folder structure and use include to add other files. Make sure files don't get longer than 200 lines
• For reasonably sized projects, use the MVC structure
• If you are storing user data, especially passwords, you must use a framework like Laravel, because you really really shouldn't mess with storing that stuff yourself
• PHP is notorious for ugly code, so be aware of this and write your code extra clean
• Always use PHP 7.1+

This is an extension of the PHP part of this file

• Write your WordPress code along the rules of the WordPress Codex
• Write variables using underscores (snake_case), not camel-case, because WordPress does not allow camel-case, so write variables like this_is_an_example
• Don't change anything in the core files or existing plugins/themes! Use hooks, make a plugin out of it, or add it to the child theme
• Don't hardcode paths, use functions like get_stylesheet_directory_uri
• Never write MySQL queries yourself, use $wpdb
• Enqueue your stylesheets by hand, not just in the style.css file
• For your custom styles and scripts, use Webpack or Gulp
• Use separate development, staging and production environments
• If possible, use the tools from Roots.io

• For Python code, the PEP 8 Style Guide should be followed
• For Docstring Conventions, check PEP 257 Docstring Conventions
• Always write your code in Python 3, if possible
• To ensure your code will not just run on your computer, make use of 'virtualenv', to standardize, Tox is a great tool, or you can use Docker of course
• Make sure there is always a requirements.txt file available, so dependencies are the same on different environments
• Where possible, use type checking

Some final words of this Coding Guidelines file:

The following sources are used for the creation of this Coding Guidelines file, please also read the following sources (you don't have to go in depth), because of course we couldn't add every single usable detail in this file.

• Airbnb Javascript standards
• Javascript project guidelines
• Sitepoint SASS project architecture
• SASS Guidelin.es, please read this part for some great tips
• Altavia ACT styleguide
• Gitignore creator
• WordPress Codex
• Roots.io
• Wikipedia - DRY
• Fibonacci
• Yarn
• BEM

• This repo for Parcel/Handlebars development
• Mega Boiler Plate

• Luciano Nooijen - Bytecode Digital Agency B.V.
• Jeroen van Steijn - Bytecode Digital Agency B.V.