gridonic / coding

🖥 Our coding manual.

Coding manual

Our coding manual represents everything we need to know in order to keep a consistent coding style and make collaboration a breeze.

Table of contents

1. Guidelines
2. IDEs / Editors
3. Linters
4. Recipes
5. Best practices

Guidelines

See the ./guidelines folder for a collection of language specific coding guidelines.

IDEs / Editors

To maintain consistent coding styles between different editors and IDEs, we use EditorConfig.

Have a look at the .editorconfig file for any details.

Linters

[…] generically, lint or a linter is any tool that flags suspicious usage in software written in any computer language. […] Lint-like tools generally perform static analysis of source code.¹

Currently we have configuration files prepared for those linters:

• ESLint (.eslintrc)
• stylelint (.stylelintrc)
• PHP_CodeSniffer for Drupal 8 (phpcs.xml.dist)

¹ https://en.wikipedia.org/wiki/Lint_(software)

Recipes

Have a look at the repository’s Wiki for a collection of recipes regarding specific coding challenges / topics.

Best practices

Want to know how we write constructors, handle state delegation or use the factory pattern? Or what’s in general the best practice to write a, b or c? Have a look at our CodePen account or check out the Wiki.

gridonic.ch ・ gridonic.github.io ・ @gridonic

coding's Issues

Use `master` branch only

For now, I don't see any benefit of having a separate develop branch in repos like this. We're not deploying multiple states of an application anywhere, for bigger additions, separate branches along with PRs should be used anyway.

Are you all good with removing the develop branch? @dschenk @mzdr

Add Android and iOS guidelines?

Anything you’d like to add @jfierz or don’t we mind?

Basic ES6 example application

We should have a basic (vanilla) ES6 example application. Regarding that I have question:

How do we handle the actual browser implementation? Do we transpile it while building and serve a browser-ready .js file? Or do we use an ES6-ready loader library like SystemJS for instance?

Since we did the transpiling thing on our website and considering the upcoming success of HTTP2 I would go for the SystemJS (or anything similar) solution, since this provides the possibility to actually make use of the advantage of having small components which are loaded on demand rather than serving one big .js file and only having the components as source files.

@gridonic/core Any feedback from you guys?

Automatically "fix" code smell issues in SASS

I think we should add something like http://csscomb.com/ in order to enforce and automatically correct specific formatting aligned with our guidelines.

Your take on this @mzdr?

Add recipes

We should use recipes for common pitfalls, problems or tasks that have been solves in projects. Examples for recipes could be:

• check and ensure a particular node + npm version in a project (js)
• browserify watch + watchify (js)
• symfony assets versioning with .htaccess and build_version (js + symfony)
• (unit) testing (preferably ava, otherwise qunit?)
• styleguide generation (styledown?)
• css generation (sass, postcss)

How to serve assets with HTTP2?

As the HTTP2 protocol (originally started out from the SPDY protocol) is now supported^[2] among all major browsers in all recent (and lots of older versions^[3]) I thought a lot about our/my typical approach on how to build/serve assets of a website.

Due to the restrictions of HTTP1.x we used to concatenate CSS and JS files to improve loading performance of websites. There are several other techniques like domain sharding for instance, which doesn't really touch my typical type of work, but is now going to get obsolete by HTTP2.

There are quite a few articles out there who share the same opinion:

We’ll be able to cut the following activities out of our regular routines:

Concatenating CSS and JavaScript. Organizing your assets during development according to the sections of your application they are used will make much more sense, because HTTP requests are cheap on HTTP/2.^[1]

HTTP/2 and You by Adam Henson, 18 March 2016

This is everything-you-thought-you-knew-is-wrong kind of stuff. In an HTTP/2 world, there are few benefits to concatenating a bunch of JS files together, and in many cases the practice will be actively harmful.^[2]

Building for HTTP/2 by Rebecca Murphey, 25 November 2015

All that means not only are the old HTTP1 techniques not needed, they'll actually make things slower. You may be loading assets that are not required for the page being viewed (concatenation and spriting are likely to do this), and sharding invokes DNS lookups which slow things down, despite HTTP2 meaning you don't need to shard in the first place.

The long and short of it is; when you build a front-end to a website, and you know it's going to be served over HTTP2 - you need to ensure you're not using legacy HTTP1 performance techniques that are going to harm the site under HTTP2.^[3]

HTTP2 for front-end web developers by Matt Wilcox, 03 March 2015

However, concatenating files is no longer a best practice in HTTP/2. While concatenation can still improve compression ratios, it forces expensive cache invalidations. Even if only a single line of CSS is changed, browsers are forced to reload all of your CSS declarations.^[4]

HTTP/2 For Web Developers by Ryan Hodson, 10 December 2015

So how do we get rid of the concatenation? This is what I have in mind and would like to be discussed.

I've set up a simple method called detectComponentsFromMarkup() in the App class which is looking for DOM nodes with a specific class pattern. The pattern is pretty simple.

<div class="@$component-name">My shiny component.</div>

So you have the name of the component and two special characters. Where @ means that the component is requiring CSS and $ means it is requiring JavaScript.

I do not insist on this pattern or implementation rather on the approach. I don't care if it's all done by data-* attributes or with a class pattern or anything else.

In this case our app would inject the CSS of this component into the document and would tell the App to require/import the JavaScript parts of the component. It's also setting up the correct CSS class selector so that the injected CSS will have any effect. So far so good…

There is still quite some effort to put into this as I don't know by now how to handle the "injection" of the components JavaScript code. There are quite a few factors like ES6 modules, import/export syntax, to transpile or not, and dynamically loading using SystemJS (or similar libraries) that make it a bit tricky. I'm still investigating, but maybe one of you guys already has a good idea to throw in?