Developer Guide

# Guidelines

# Themes

# From Scratch

When starting from scratch, we prefer to use our own custom starter theme VG+ for Shopify Development. This theme's technologies are outlined in the Tech Stack section.

Generally speaking, the Lead developer will take care of the repository setup, basic updates on the theme to ensure it's descriptive of the client being serviced, and the style guide. Sometimes even the homepage gets completed for you, if the Lead is feeling frisky. This should give you more than enough to get started.

# Existing

When working from an existing theme, it's best to try and follow the established standards in the theme itself. This can mean you will need to work with outdated (e.g. jQuery) or custom libraries, spaghetti code, etc.

In this case, it's best to stick to the The Boy Scout Rule:

"Leave your code better than you found it"

# Architecture

We like to keep our theme customizations’ code separate from the themes’ base code wherever possible. Modularity is the name of the game.

# From Scratch

In VG+, all custom JS and CSS should live within the src folder.

The src folder contains nested folders for relevant SCSS and JS, and they are compiled out and imported into the relevant places in the theme.liquid file already.

# VG+ Helpers

There are many helper classes and functions already built into the codebase. Some of these include:

  1. Built in default styles for elements (elements.scss) and existing Style Guide
  2. Helper CSS Variables (styles.css.liquid)
  3. Flexbox Grid System (_grid.scss)
  4. AJAX Cart & Cart Page With Vue & Vuex
  5. PDP Purchase Area (_rhpa.js) with Vue & Vuex
  6. All major Shopify pages
  7. Several starter Sections for Homepage/Pages, OS2 compatible
  8. Bundle Starter Page
  9. Collection filtering with tags, sizes, vendors, colors, etc.

# Existing Code + New Feature

When we want to add new features, it's best to encapsulate them into their own files. This keeps our customizations separate from the themes’ base code, usually in a Snippet.

ee-styles.css.liquid - contains custom CSS written by Electric Eye

ee-scripts.js.liquid - similarly contains custom JS

Any custom .liquid files should live within the snippets folder, and be imported into the relevant file in the templates folder.

NOTE: if you plan on using Liquid variables, use .liquid as a suffix; if you don't, use raw .css/.js files and put them in the assets folder.

If you are modifying an existing feature, or adding new code to support one, it's best to keep the code in the same area, ideally accompanied with a comment.

Furthermore, if this .liquid file is small enough that you can reuse existing code without modifying it, and contain the relevant overrides to JS or CSS within that file, that is also acceptable and encouraged.

# Code

# Naming

We don’t really have a naming convention, but in general it's best to use kebab-case for CSS, and camelCase for JS.

# Linting

Within the custom theme, we have some linters (ESlint, StyleLint, EditorConfig, etc.) configured to help you keep your code consistent with our standards. Outside of that, there are some things to note that aren't able to be defined with linters.

# Comments

No specific requirement for this, but if you are writing a complicated piece of logic, or made a specific change that isn't "intuitive", it's always best to add a comment explaining why or what it was for. Again, remember the Boy Scout Rule!

# (S)CSS

Try to keep these to no more than two or three nested selectors to avoid code bloat. Use CSS specificity wisely, and remember it's called cascading style sheets for a reason.

# JS

The best general rule of thumb is to try and match what is existing in the code, but we do have some guidelines to follow.

# Whitespace

In VG+, we use two spaces for everything, and it will format all files for you based on that rule, but there are a lot of exceptions to this rule in client themes.

As long as it’s human-readable and correctly indented within the file you are working, it’s probably fine!

# Spaghetti

Belongs in Italian kitchens, not in code repositories. Please keep your code modular, clean, easily editable and refactor whenever possible!

If you're unfamiliar with this phrase, refer to the almighty Wikipedia for more information.

# Parting Thoughts

A Great Programming Sage once said: "Today's code is tomorrow's trash"

Remember that we all program differently, and as developers we are always learning. At the end of the day, we all have one goal: To learn cool stuff, and to make cool stuff with it.

Be kind to yourself, and to others. Help each other when you can, and never be afraid to ask questions, show off your accomplishments, or share something you learned or discovered. Some of the best discoveries and practices come out of a simple "Hey, check this out!"