Coding Standards

Code Editors

Most HTML code should be written in a proper code editor. Small changes such as just text changes can be done directly in the Magento Admin interface but anything more than that should be done in a proper code editor.

Do NOT use a Word Processor

Word processors are great for creating word documents. They are not designed for writing code and should NEVER be used for writing code. There are many reasons why word processors should not be used for writing code but the major reason is that word processors often automaitcally change characters to stylize them. For example in a word processor you might type in <a href="some-link">Some Link</a> and the word processor will automatically change those quotes into special direction quotes (<a href=“some-link”>Some Link</a>) that look fancy (which is disirable for word processing) and this might break the entire website, everything below this will not be displayed properly. If you edited a banner on the top of the checkout page and broke the checkout page we could lose hundreds of thousands of dollars before we find and correct the mistake. And so I stress DO NOT USE WORD PROCESSORS FOR WRITING CODE.

Advantages of a Code Editor

Code Editors will provide you with a nice interface for editing code, this includes syntax highlighting, tag matching, auto-complete (auto tag closing) and other useful tools for writing code.

Suggested Code Editors

If you fail to use a code editor and instead decide to break our site the entire Development Department will yell at you.

Spaces Not Tabs

All code should be indented using 2 spaces, not tabs. Tabs are displayed differently in each editor and will cause your code to "run away" (become very indented) in the Magento Admin interface. To avoid these problems all code indentations should be done with 2 spaces and not tabs. Most code editors (all of the ones suggested above) allow you to configure them to automatically indent with 2 spaces when you press the "tab" key. I use VS Code and in VS Code this can easily be configured by clicking the bottom on the bottom right as shown here:

If you fail to use spaces and instead decide to use tabs, the Developement Department will not care as our code editors can automatically convert them and fix this.

Single Vs. Double Quotes

HTML does not care if you use single or double quotes for element attribute delimiters, as long as whichever you choose is not contained within the attribute value.

If you want to use a single quote within the value you will have to "escape" the character using a backslash (\), for example <img src='image.jpg' alt='Ethan\'s Dog' />, because of this it is easier to just use the oposite quote as the delimiter <img src='image.jpg' alt="Ethan's Dog" />.

Because I often find that I need to use double quotes within the value more often than single quotes, and because I like to keep things consistent I use single quotes as attribute delimiters.

When inserting an image using the Magento Admin interface it will produce code that looks like this: <img src="{{media url="wysiwyg/common/style-guide/spaces-not-tabs.png"}}"" />. You will notice that they use double quotes within double quotes, but becase this inner value is a handlebars template that is compiled on the Back-End before being sent to the browser this works, but it will break your syntax highlighting within your code editor. Because of this the attribute delimiter should be manually changed to single quotes (do not change the inner quotes to single quotes or it will not work).

If you fail to use single quotes as attribute delimiters, no one will care as long as it works, I would suggest just trying to be consistent.

Editing Code

To change HTML code you should follow these steps:

  1. Create an HTML document on your local machine (I.E. on your desktop)
  2. Open the document in your code editor
  3. Copy and paste the code from the Magento Admin interface into this HTML document
  4. Edit the code
  5. Copy and paste the code from the HMTL document back into the Magento Admin interface