pietrox/style-guide

:newspaper: dwyl's visual and coding style guide

dwyl Style Guide

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.

Contents Guide

• Why?
• General guidelines
  • 2 Space indentation
  • Intelligently commenting your code
  • Single quotes
• Git
  • Issues
  • Commits
  • Pull requests
  • Naming repositories
• Markdown
• CSS (WiP)
  • General points
  • Indentation
  • Naming conventions
  • Grouping properties
• JavaScript (WiP)

Why?

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.

General

Indentation

2 space indentation (see our developer setup guide for tips on setting this kind of thing up in your text editor).

Intelligently commenting your code

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*/
  ...
}

Quotes

Use ' single quotes ' everywhere, except:

• When constructing a string including properties which are themselves denoted by single quotes:
  e.g: var str = "<a class='big' href='/mylink'>click me</a>";
• When manually creating a JSON object/file (as these are not valid JSON)

Git

Issues

• Your issue title should be short but descriptive
• Use labels please!
• If you want someone specific to look at your issue, assign it to them
• When referring to a file, always do so within the context of a specific commit (as that file could be constantly changing and your issue will quickly stop making sense)
  • Example: https://github.com/dwyl/style-guide/blob/dea0009638b7923521a13190f17090af37a7ff22/README.md and not https://github.com/dwyl/style-guide/blob/master/README.md
  • To get this URL, go to the History tab on the top right of your document and choose a commit form the list that appears
  
• When referring to a specific piece of code, include the line number that code is on
  • You can either add this by add #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) or
  • Go to a specific commit (as above), click on 'View' and then click on 'Blame' in the top right hand corner
  + You can now click on any line and the line number will be added to the URL

Commits

• Use the third person present tense in your commit messages, as if you were finishing off the sentence "This commit message..."
  • For example "adds riot.js to index" or "fixes #12 disappearing content bug"
• Include an issue number in every commit message
  • The commit message will then appear within that issue and ensure traceability of every contribution

+ Keep your commits **'common sensibly small'** + A good rule of thumb is that _if you have to use the word 'and' in your commit message, you're probably doing too much in a single commit_ unless the things you're committing are intrinsically tied together. + **If you're pairing**, consider giving your pair some credit in your commit messages by including their initials:

+ Did you know you can [use emojis in your commit messages](dwyl/start-here#49)? It's totally a thing.

Pull Requests

Good 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

Reviewing pull requests

• Inline comments on github are very useful when reviewing pull requests, both for traceability and speed of review.

Naming repos

• We favour one-word names for node modules (make sure the name is available on npm) and descriptive names for everything else (especially tutorials!)

Markdown

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)

CSS

General points

• Use classes, not IDs as your hooks
• Explicitly select what you want rather than fumbling around the HTML structure searching for hooks - practice good selector intent
  • i.e. if you're styling a site's navigation, style primary-nav instead of header ul
• Pick class names that are as re-usable as possible (e.g. pick primary-nav over site-nav)

Indentation

CSS indentation should mirror the HTML structure.

.article {}
  .article-quote {}

Naming conventions

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:

• Semantic class names (e.g. not green-btn but primary-action-btn)
• BEM-like modifier syntax (using --), e.g. modifying .site-logo to .site-logo--xmas

Grouping properties

• Group properties by type
  • For example, font and text-align properties would sit together, as would border, display, height and width properties
• For further organisation, favour alphabetical ordering (grouping by type always takes precedence)

JavaScript

• Use semicolons please!
• No trailing commas on object declarations:

var example_object = {
    name: 'dwyl',
    age: 1 //<-- Having a comma after the '1' would be a 'trailing comma' 
};

Variable naming

• If you can, use a descriptive one word variable name
• If one word isn't enough, use underscores to separate words (snake case) and not camel case: var example_variable

dwyl/summer#22