A style guide is a set of standards [which] establish and enforce style to improve communication.
_https://en.wikipedia.org/wiki/Style_guide_
This style guide is a work in progress and is being put together over the course of #dwylsummer and the rest of our work.
Please open an issue if you have an questions or comments at all!
For now, the visual and coding styles will live in the same repo. If the size of this readme gets out of hand or if we have a lot of requests to separate them, we'll do so.
Consistency.
Every developer likes to do things their own way.
Even though we have our own idea of what maintainable code looks like, the important thing isn't how many spaces we indent our code with but that everything is consistent so new people don't have to work through personal formatting quirks of previous developers and can focus on the code.
2 space indentation (see our developer setup guide for tips on setting this kind of thing up in your text editor).
We favour the intelligent approach.
Many developers (not us) believe that well-written code doesn't need comments. Whilst it's true that adding too many comments to your code makes it unreadable. The key is to put yourself in the shoes of the next person who has to work with your code.
If you feel your code is as simple as it can be but what it doesn't isn't immediately obvious, then add a comment.
Good examples of this are when something in your code in one location necessarily has an impact elsewhere.
//JavaScript example
else {
mod = moduleName.replace('.js', '.\.js'); //escape .js for regex
}
/*CSS example*/
.article {
position: relative; /*contains `.quote` which is positioned absolutely*/
...
}
Use '
single quotes '
everywhere, except:
var str = "<a class='big' href='/mylink'>click me</a>"
;#L
and the line number to the end of the URL (e.g. https://github.com/dwyl/hapi-socketio-redis-chat-example/blame/b26354e3f37b2bdd0414b9b01bfe45db7ee9504e/lib/chat.js#L6) orGood pull requests (PR) reduce the back and forth required between the person submitting the PR and the assigned reviewer, saving everyone time.
For our guidelines on contributing pull requests to dwyl projects, please see: https://github.com/dwyl/contributing
This is a good reference for markdown syntax.
For readability, we use:
_
underscores _
for italics **
double asterisks **
for bold+
plus signs for bullet points (so they're not confused with bold or italics on first glance)primary-nav
instead of header ul
primary-nav
over site-nav
)CSS indentation should mirror the HTML structure.
.article {}
.article-quote {}
For now, we don't use BEM CSS naming conventions as it doesn't provide the flexibility we feel we need during the early stages of our work.
Here's what we do use:
green-btn
but primary-action-btn
)--
), e.g. modifying .site-logo
to .site-logo--xmas
font
and text-align
properties would sit together, as would border
, display
, height
and width
propertiesvar example_object = {
name: 'dwyl',
age: 1 //<-- Having a comma after the '1' would be a 'trailing comma'
};
var example_variable