General guidelines for all code

The following code example guidelines apply to all code, whether we are talking about HTML, CSS, JavaScript, or something else.

In this article

Indentation, spacing, size

Indentation

All code should use 2 spaces for indentation, for example:

<div>
  <p>This is my paragraph.</p>
</div>
function myFunc() {
  if(thingy) {
    console.log('Yup, that worked.');
  }
}

Code line length

Lines of code should be a maximum of 80 characters long (64 for interactive examples). You should break lines sensibly for the sake of readability, but not at the expense of best practices.

For example, this is not great:

let tommyCat = 'Said Tommy the Cat as he reeled back to clear whatever foreign matter may have nestled its way into his mighty throat. Many a fat alley rat had met its demise while staring point blank down the cavernous barrel of this awesome prowling machine.';

This is better, but somewhat awkward:

let tommyCat = 'Said Tommy the Cat as he reeled back to clear whatever foreign '
+ 'matter may have nestled its way into his mighty throat. Many a fat alley rat '
+ 'had met its demise while staring point blank down the cavernous barrel of '
+ 'this awesome prowling machine.';

Even better is to use a template literal:

let tommyCat = `Said Tommy the Cat as he reeled back to clear whatever foreign
  matter may have nestled its way into his mighty throat. Many a fat alley rat
  had met its demise while staring point blank down the cavernous barrel of
  this awesome prowling machine.`;

Code block height

Code blocks should be as long as they need to be, but no longer. Ideally, aim for something short like 15-25 lines. If a code block is going to be a lot longer, consider just showing the most useful snippet, and link to the full example on a GitHub repo or codepen, say.

Guidelines for displaying examples

Size of rendered example

The MDN main content pane is about 700px wide on desktop, so embedded MDN examples must look OK at that width (set the width of embedded examples at 100%).

For height, we'd recommend keeping the rendered example at below 700px in height if at all possible, for maximum onscreen legibility.

You should also think about making your examples responsive to  some degree, so they are also useful on mobile devices.

Use of images and other media

Sometimes you'll want to include images or other media in an example. If you do:

Use of color

Lower case for hex, can use keywords for shades and primary colors (e.g. black, white, red), use more complex schemes only when needed (e.g. to include transparency)

Prefer to use keywords for primary and other "basic" colors, for example:

color: black;
color: white;
color: red;

Use rgb() for more complex colors (including semi-transparent ones):

color: rgb(0, 0, 0, 0.5);
color: rgb(248, 242, 230);

If you have to use hex colors, then use lower-case:

color: #058ed9;
color: #a39a92;

and use the short form where relevant:

color: #ff0;
color: #fff;

MDN's Fiori guidelines (for the front-end codebase) contain a useful set of colors that complement the overall MDN design.

Highlight good and bad practice examples

As you will notice from looking around these guidelines, the code blocks that are supposed to be good practice examples are highlighted with a smiley face in green, and the code blocks that are supposed to be bad practice examples are highlighted with a sad face in red.

To do this, you first use the MDN editor controls to put your code block in a <pre> block and give it appropriate syntax highlighting. The source of the code will look something like this:

<pre class="brush: js">
function myFunc() {
  console.log('Hello!');
};</pre>

To make it into a good example, you insert example-good just before the closing quote of the class attribute:

<pre class="brush: js example-good">
  ...

To make it into a bad example, you insert example-bad just before the closing quote of the class attribute:

<pre class="brush: js example-bad">
  ...

We would like to encourage you to use these. You don't need to use these everywhere — only when you are specifically calling out good and bad practices in your code.

Document Tags and Contributors

Contributors to this page: chrisdavidmills
Last updated by: chrisdavidmills,