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