Revision 34155 of Tips for writing code examples

  • Revision slug: Project:Tips_for_writing_code_examples
  • Revision title: Tips for writing code examples
  • Revision id: 34155
  • Created:
  • Creator: jswisher
  • Is current revision? No
  • Comment page created, 157 words added

Revision Content

Writing good, useful, information code examples is an art that requires balancing competing concerns.

Basic requirements

Code examples need to be:

  • simple enough to be understandable, but
  • complex enough to do something interesting, and preferably useful.

There is one overarching consideration that you need to keep in mind:

Readers will copy and paste the code example into their own code, and may put it into production.

Therefore, you need to make sure that the code example is runnable, but does not do anything that will cause an application to be insecure, grossly inefficient, or bloated in size. If the code example is not runnable or production-worthy, be sure to include a warning in a code comment and in the explanatory text.

Formatting

Refer to the Code formatting section of the MDC formatting guide.

If you add or remove lines in a code example, make sure that you update references to line numbers in the explanatory text.

Revision Source

<p>Writing good, useful, information code examples is an art that requires balancing competing concerns.</p>
<h2>Basic requirements</h2>
<p>Code examples need to be:</p>
<ul> <li>simple enough to be understandable, but</li> <li>complex enough to do something interesting, and preferably useful.</li>
</ul>
<p>There is one overarching consideration that you need to keep in mind:</p>
<p style="margin-left: 40px;"><em>Readers will copy and paste the code example into their own code, and may put it into production.</em></p>
<p style="margin-left: ;">Therefore, you need to make sure that the code example is runnable, but does not do anything that will cause an application to be <em>insecure</em>, <em>grossly inefficient</em>, or <em>bloated in size</em>. If the code example is not runnable or production-worthy, be sure to include a warning in a code comment and in the explanatory text.</p>
<h2 style="margin-left: ;">Formatting</h2>
<p>Refer to the <a href="/Project:En/MDC_style_guide#Code_formatting" title="/Project:En/MDC_style_guide#Code_formatting">Code formatting section of the MDC formatting guide</a>.</p>
<p>If you add or remove lines in a code example, make sure that you update references to line numbers in the explanatory text.</p>
Revert to this revision