A style guide sets standards and improves communication. ~ wikipedia.org/Style_guide

This style guide is a work-in-progress we need your help to maintain and extend it. 🙏
If you spot something that can be improved or have a question, please open an issue. 💬

• Why? 🤷🏻‍♀️
• General 👋
  • Indentation ✌️
  • Intelligently Comment Code 💬
  • Quotes 🧵
• Git 👩‍💻
  • Issues 📝
  • Commits ✨
  • Pull Requests 🚀
    • Reviewing PRs 👀
    • Use In-line Code Suggestions in PRs! 📝
  • Naming Repos 🌹
  • Naming Files 🗄️
• Markdown ⬇️
  • Use Descriptive Link Text 🔗
    • Avoid One-Word Non-Semantic Link Text 👎
  • Semantic Line Breaks ↩
    • Example 💡
    • Exception? 💭
• CSS 👩‍🎨
  • Formatting 🦄
  • Naming Conventions 🍓
  • Grouping Properties 👥
• JavaScript ☕
  • Variable Naming 🐍
  • README Badges?
• Recommended Reading 📖
• Please Star ⭐

Why? 🤷🏻‍♀️

Consistency. 😍

Creative people often like to do things their own way. That's great if you are working alone but not so good on an established team. Many different styles leads to projects that look wildly different from each other. This slows down new people and wastes time. We need everything consistent so new people don't have to work through personal formatting quirks of previous engineers and can focus on the feature. 🎯

General 👋

We follow a handful of general principals to keep our projects running smoothly, easy to onboard and maintain.

Indentation ✌️

We use 2 spaces for indentation see: developer setup guide for tips on setting this kind of thing up in your text editor.

This isn't up for debate. There is no tab key on Smartphones; which is the most ubiquitous input device. If we don't want to exclude people who don't have a full-size keyboard, we can only use spaces.

💡 Tip: use the .editorconfig file to automatically define the indentation settings in your editor.

Intelligently Comment Code 💬

We favour the intelligent approach to commenting code.

Many developers (not us) believe that well-written code doesn't need comments. Whilst it's true in a tiny hello world app where there almost no code, it's not the case in a project with many thousands of lines that has to be groked by several people of varying experience/skill levels. Yes, in some cases adding too many comments can also make it unreadable. The key is: put yourself in the shoes of the next person who has to work with the code.

If you feel your code is as simple as it can be but what it does 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 */
  ...
}

Note: try not to be offended if someone reviewing your PR/code asks you to please add comments. It's because they have experience of reading lots of code and want to help the next person understand it the way you do now. 😊

Quotes 🧵

Use " double quotes " for Strings, except when constructing a string including properties which are themselves denoted by single quotes: e.g: var str = "<a class='big' href='/register'>Register To Comment</a>";

Most programming languages we use, e.g: HTML, JavaScript, Dart allow single and double quotes to be used interchangeably. But Elixir and JSON do not. String in Elixir must use double-quotes, and valid JSON keys/values must be surrounded by double-quotes. This is why we use double-quotes for Strings; it makes everyone's life easier/faster when switching between code bases.

Again, this isn't a debate. 😊

Git 👩‍💻

If you are new to Git and/or GitHub we recommend reading our Git Guide: dwyl/git-guide

Issues 📝

GitHub Issues are how we do the vast majority of our asynchronous communication. We follow a simple set of rules that streamline everything:

1. Your issue/pull request title should be short but descriptive

2. Use labels please! see: dwyl/labels

3. To request the input of a specific person on an Issue or PR, mention them in a comment and if you want to delegate a task assign it to them. However, don't just assign issues/PRs without any explanation, that's called Buck passing

4. 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

5. When referring to a specific piece of code, include the line number that code is on. 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 ✨

1. Use the third person present tense in your commit messages, as if you were finishing off the sentence "This commit message..." e.g: "adds atm.js to index.html #420" or "fixes disappearing content bug #12"
2. Include an issue number in every commit message

• The commit message will then appear within that issue and ensure traceability of every contribution.

1. 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.

1. 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?

Pull Requests 🚀

A good pull request (PR) reduces 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: dwyl/contributing

Reviewing PRs 👀

Use inline comments on github when reviewing pull requests, both for traceability and to help the person submitting the PR improve.

Use In-line Code Suggestions in PRs! 📝

When there is a simple/obvious code or copy change that can be made in a Pull Request to save time, simply use the code suggestion button in the PR comment.

Hover over the line of code where you'd like to add a comment, and click the blue comment icon:

to suggest a specific change to the line or lines, click ±, then edit the text within the suggestion block.

See: docs.github.com/en/pull-requests/collaborating-with-pull-requests

Naming Repos 🌹

We favour one-word names for repos and node modules (make sure the name is available). e.g:

• fields
• gcal
• link
• useful
• quotes

When the name we want is "taken" on the package system we are using, we add more words to the repo/package name separated by hyphens. e.g:

• aws-sdk-mock
• elixir-auth-github

Note: we occasionally use underscores in repo names where we want to match the repo name to the module name e.g: auth_plug or dart_multihash However we try to minimize this and prefer hyphens.

If a single-word name is not possible, use descriptive names (especially for tutorials!) e.g:

• javascript-todo-list-tutorial
• phoenix-liveview-counter-tutorial
• phoenix-liveview-realtime-cursor-tracking-tutorial

The more descriptive the title the easier it will be for someone to find when searching.

Naming Files 🗄️

Always use lowercase names for files and directories. The exception to this are the files GitHub creates by default e.g: LICENSE, README.md, CONTRIBUTING and CODE_OF_CONDUCT, etc.

Markdown ⬇️

We recommend being competent in Markdown as we use it every day. markdown cheatsheet. 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)
• Section Headings should always be followed by a blank line.

Use Descriptive Link Text 🔗

We prefer to either use super descriptive link text e.g:

Learn how to do what you love by reading the 
[start here repo](https://github.com/dwyl/start-here).

Or simply use the URL as the link text e.g:

Read our "start here" doc to learn how to do what you love:
[dwyl/start-here](https://github.com/dwyl/start-here)

This is infinitely better than non-semantic link text (inaccessible!) which should be avoided at all costs!

Avoid One-Word Non-Semantic Link Text 👎

Avoid including non-semantic link text e.g:

You can find more info [here](https://en.wikipedia.org/wiki/Computer_security) on Cyber Security.

or

[Click here](https://en.wikipedia.org/wiki/Pok%C3%A9mon_the_Series:_XYZ) for more details on **XYZ**.

Both of these examples are horrible for accessibility and should be avoided.

Read more: mtu.edu/accessibility/training/web/link-text/

Semantic Line Breaks ↩

When writing prose in markdown or documentation text blocks for code, we try to limit the line length to 80 characters (within reason) to aid readability/reviewability on smaller screens e.g: Laptops, Phones, etc.

We follow the "Semantic Linefeed" rule (or "one thought per line") whereby we insert a break each time there is a "thought joining word" such as "and", "or", "but", "therefore", "because", etc. thus our sentences are short and broken out by meaning.

Example 💡

Avoid super long lines of text:

MR. Jones, of the Manor Farm, had locked the hen-houses for the night, but was too drunk to remember to shut the popholes. With the ring of light from his lantern dancing from side to side, he lurched across the yard, kicked off his boots at the back door, drew himself a last glass of beer from the barrel in the scullery, and made his way up to bed, where Mrs. Jones was already snoring.

This super long line of text is un-reviewable/maintainable. 😢

Break it out by semantic sections:

MR. Jones, of the Manor Farm,
had locked the hen-houses for the night,
but was too drunk to remember to shut the popholes.
With the ring of light from his lantern dancing from side to side,
he lurched across the yard,
kicked off his boots at the back door,
drew himself a last glass of beer from the barrel in the scullery,
and made his way up to bed,
where Mrs. Jones was already snoring.

Where you place the line breaks is not as important as having them. i.e: just break up the long lines into smaller chunks that each have a thought, and try to keep them less than 80 chars where possible/practical.

Exception? 💭

The obvious exception to this is when there is a URL that is longer than 80 chars. In those instances we will place the URL on its' own line which again, makes it easier to read/maintain/update. e.g:

We follow the ["Semantic Linefeed"](https://rhodesmill.org/brandon/2012/one-sentence-per-line) rule in our markdown documents.

Note: That sentence requires horizontal scrolling, a time-suck. ⏳😕

Becomes:

We follow the
["Semantic Linefeed"](https://rhodesmill.org/brandon/2012/one-sentence-per-line)
rule in our markdown documents.

Use your best judgement. Keep it easy for the humans to read! 👩🏻‍💻

CSS 👩‍🎨

• Learn and Use Tailwind CSS dwyl/learn-tailwind great interface is essential to a great experience.
• If you use a separate CSS file, 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)

Formatting 🦄

CSS formatting and indentation should mirror the HTML markup structure, e.g:

.article {}
  .article-quote {}

Naming Conventions 🍓

When we need to apply styles to an element, 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 e.g: 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:

const 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) not camelCase
  e.g: let auth_token = "e2jxyz.etc.etc"

README Badges?

We use badges extensively in our projects. See: dwyl/repo-badges

Recommended Reading 📖

• 29 Well-Designed Online Style Guides webdesignledger.com/29-online-style-guides
• Tips on writing Descriptive Link Text: mtu.edu/accessibility/training/web/link-text
• Useful tips for better commit messages: thoughtbot.com/5-useful-tips-for-a-better-commit-message
• CSS for Software Engineers: speakerdeck.com/csswizardry/css-for-software-engineers

Please Star ⭐

The best way to let everyone know you have read and understood this style guide is to star the GitHub repo. 🌟

Thank you! ❤️