Skip to main content

Create code examples

To develop effective code examples for your users, follow these best practices.

Users use code examples to:

  • Assess the suitability of a given feature or API for a task.
  • Learn or explore a language or technology.
  • Write and debug code.

Many users copy example code from documentation into their own code, and either use it as-is or adapt the example to their own needs. For this reason, it is very important that code examples are easy to understand and use, and do not introduce unintended problems into the user's codebase.

Design for usability​

  • Identify the tasks and scenarios that are meaningful for your audience, and create examples that illustrate those scenarios.
  • Create concise examples that demonstrate typical development tasks. If you need to provide multiple examples, start with simple examples and build up complexity after you cover common scenarios.
  • Only include extra code if it is within the scope of what your example demonstrates. For example, if a code example only works on a specific platform, mention that in the text; don’t use if or try-catch statements to restrict the platform.
  • Use descriptive and human-readable class, method and variable names.
  • Use explicit types to declare the data type of a variable. Compared to implicit types, explicit types provide greater clarity into what the data type of a variable is. When you use explicit types, the doc tools are able to automatically add links to the Unity types used in the code sample.
  • Use comments to explain details and help developers determine what to modify. Comments in scripting examples must be descriptive and concise, and adhere to the same style guidelines as the rest of the documentation.
  • Show or describe expected output, either in a separate section after the code example or by using code comments within the code example.
  • Where code must be understood by users with various experience levels, prioritize readability over performance or completeness, but clarify that you have done this. To see this in practice in the User Manual, read Creating a simple render loop in a custom render pipeline.
    • If you need to provide a code example that is clear but not efficient, make this clear in a comment at the top of the code; for example, “This example demonstrates the clearest workflow, rather than the most efficient runtime performance."
    • If you need to provide a code example that is simplified for readability, make this clear in a comment at the top of the code; for example, "This code example is a simplified example of [x]. It demonstrates [y]."
  • Before the code example appears in the page, provide an overview (one or two sentences) in the main body of the page to describe what the example code does, and provide the requirements and dependencies for using or running the example.

Design for quality​

  • Write code that adheres to the Unity Coding Style Guidelines.
  • Write secure, safe code. For example, validate user input in cases where the example could compromise security, never hard-code passwords in code, and use code-analysis tools to detect security issues. Don’t write examples that require the user to enable unsafe code.
  • Compile and test your code example. Code examples that don't compile break the main build for API documentation, and can break the user’s codebase.
  • Do not provide code that doesn’t work as an anti-example. Anti-examples can be confusing because users often skim read the documentation, or copy and paste example code. Instead, mention limitations in the text.

Additional resources​