Code Editing

Our products are technical, and we often need to show people code or let them edit it. Use these guidelines when designing interfaces that have code snippets or editors.

Code Editors

Use code editors when users need to write code, such as experiment Javascript or CSS. A good code editor has:

  • Text in a monospaced font
  • Line numbers (when more than one line)
  • Syntax highlighting
  • Inline error checking
  • A default comment that provides a code sample, or explains what type of input it is expecting

If the code needs to be compiled or ran (such as with experiment Javascript), there should be a clear primary action for users to see the output of their code, as well as a cancel button to clear out their changes.

Sample code editor.

Default Comments

Default comments are a helpful way to provide examples of code, or messaging what the code is used for in the code area. A good idea is to give the user a complete example they can modify, un-comment, and run. Be clear and concise when writing a default comment. Users should easily be able to understand how to use it and how to modify it.

Sample default comment.

Code Snippets

Use code snippets when you need to show a piece of code that users will copy and paste into their site or app. Snippets are not editable. If the snippet needs an ID or a certain variable to be inserted, you should insert the ID into the snippet.

Sample default comment.

Copying

Code snippets should be easily copyable. Display them in a read-only input box that selects the text when the user clicks into it, and provide a copy button next to the input. This makes it easy to copy with a keyboard shortcut or by clicking a button. This also avoids errors while copying, such as not selecting the entire snippet.

Snippet Usage

There should be a clear message about what to do with the snippet after it's copied. For example, "Paste this into the <head> tag of your website." The message should also include what the snippet will do, such as "This will allow code to run on all of your websites."