Goals for the Code snippet pattern

Goals

Code clarity

A key goal is code clarity - the user should be able to identify the code they need, either to copy and use or as a reference example. It should be clear that the user is looking at code (rather than prose) and that the code is readable.

Ease of use

Code is not particularly resistant to errors: a missing character (or in some languages, a space or tab) can lead to errors so the user should be able to select and copy the code easily. It should be clear which version, platform or other switchable type is being used - in addition, showing a title and description can help a user who is skimming the page (or arriving from a search engine) to immediately understand the significance of the code snippet.

Modularity

Not all code examples are the same and this pattern should be modular and extensible - allowing the documentation author to decide which elements to use and which are not required.