4.0 Coding conventions

[Paul Clarke]

Things are coming along with SilverStripe 4 alpha and to help keep things clean from the get-go we would like to progress some of our standards and conventions around structure of code, the use of CSS/SCSS and its naming conventions.

As you all know we are basing our styles off Bootstrap 4 which uses some pretty good conventions but we’re taking the opportunity to build upon those conventions by using BEM, which is more strict in its use but will help to make the styles more manageable as it grows. We are also liking the simplicity of the AirBnb guides and are thinking to possibly use this as a first reference.

We’ve done a bit of a test run with some of the work used in Alpha to see if BEM would conflict with Bootstrap and so far there hasn’t really been any major concerns, but of course it's still early days. In addition to this we will be using the principles behind ITCSS to structure the inclusion of styles. You can take a look at first components to get an idea of how things are structured on GitHub (keep in mind this is work in progress).

BEM uses double underscores and dashes: .block__elem--mod { }
Block: The sole root of the component.
Element: A component part of the Block.
Modifier: A variant or extension of the Block.


We’re not currently using any prefixing to avoid conflicts for any of our new components but will be considering it as we continue to work making React components.

As always it would be good to hear people's thoughts on any of this stuff. 

There's a lot of work ahead for everyone to clean up the front-end of the CMS but its going to be satisfying for sure!

[Zenmonkey]

When working with nested SCSS I find it helpful to break up the code into more readable chunks. I try to avoid neting more than root + two levels. And never uanving more than 3 sets of selectors per nest. Basically I try to keep a nest under 50 lines (preferably 40 lines) of code to make sure see a whole nest on screen at once. I tend write it, then refracrtor to break it up in a logical way.

I find Chris Coyiers style guide to be quite helpful  https://css-tricks.com/sass-style-guide/

[Ingo Schommer]

Thanks Richard! BEM discourages selector nesting as well - as you can see from the new CSS which we've written, it typically only goes to root + one level.

We'll also enforce some of these rules through CSSLint - Sam has written a PoC for this on the asset-admin module: https://github.com/silverstripe/silverstripe-asset-admin/pull/115

One of these rules is around selector nesting - we can choose to show a warning in your IDE (if set up with CSSLint), or even break the build on a pull request with too many levels.

Great to see this level of professionalisation in the CSS space :)

Ingo

[Ingo Schommer]

We've now merged some CSS docs which reflect what was discussed here: https://github.com/silverstripe/silverstripe-framework/pull/5389