You cannot select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
193 lines
9.5 KiB
HTML
193 lines
9.5 KiB
HTML
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
<html>
|
|
<head>
|
|
<title>Arduino - StyleGuide </title>
|
|
<link rel='stylesheet' href='arduino.css' type='text/css' />
|
|
</head>
|
|
<body>
|
|
<div id="page">
|
|
<!--PageHeaderFmt-->
|
|
<div id="pageheader">
|
|
<div class="title"><a href="http://www.arduino.cc"/>Arduino</a></div>
|
|
<div class="search">
|
|
<!-- SiteSearch Google -->
|
|
<FORM method=GET action="http://www.google.com/search">
|
|
<input type=hidden name=ie value=UTF-8>
|
|
<input type=hidden name=oe value=UTF-8>
|
|
<INPUT TYPE=text name=q size=25 maxlength=255 value="">
|
|
<INPUT type=submit name=btnG VALUE="search">
|
|
<input type=hidden name=domains value="http://www.arduino.cc/">
|
|
<input type=hidden name=sitesearch value="http://www.arduino.cc/">
|
|
</FORM>
|
|
<!-- SiteSearch Google -->
|
|
</div>
|
|
</div>
|
|
<!--/PageHeaderFmt-->
|
|
<!--PageLeftFmt-->
|
|
<div id="pagenav" style="text-align: right">
|
|
<div style="float: left;">
|
|
<p><a class='wikilink' href='http://arduino.cc/en/Main/Buy'>Buy</a>
|
|
|
|
|
<a class='wikilink' href='http://arduino.cc/en/Main/Software'>Download</a>
|
|
|
|
|
<a class='wikilink' href='Guide_index.html'>Getting Started</a>
|
|
|
|
|
<a class='wikilink' href='http://arduino.cc/en/Tutorial/HomePage'>Learning</a>
|
|
|
|
|
<a class='wikilink' href='index.html'>Reference</a>
|
|
|
|
|
<a class='wikilink' href='http://arduino.cc/en/Main/Hardware'>Hardware</a>
|
|
|
|
|
<a class='wikilink' href='FAQ.html'>FAQ</a>
|
|
</p>
|
|
<p class='vspace'></p>
|
|
|
|
</div>
|
|
<a class="urllink" href="http://www.arduino.cc/blog/" rel="nofollow">Blog »</a> |
|
|
<a class="urllink" href="http://www.arduino.cc/cgi-bin/yabb2/YaBB.pl" rel="nofollow">Forum »</a> |
|
|
<a class="urllink" href="http://www.arduino.cc/playground/" rel="nofollow">Playground »</a>
|
|
</div>
|
|
<!--/PageLeftFmt-->
|
|
<div id="pagetext">
|
|
<!--PageText-->
|
|
<div id='wikitext'>
|
|
<p><strong>Reference</strong> <a class='wikilink' href='index.html'>Language</a> (<a class='wikilink' href='Extended.html'>extended</a>) | <a class='wikilink' href='Libraries.html'>Libraries</a> | <a class='wikilink' href='Comparison.html'>Comparison</a>
|
|
</p>
|
|
<p class='vspace'></p><h1>Arduino style guide</h1>
|
|
<p>This is a guide for writing clear Arduino examples that can be read by beginners and advanced users alike. You don't have to code this way, but it helps if you want your code to be clear to all levels of users.
|
|
</p>
|
|
<p class='vspace'></p><p>This is not a set of hard and fast rules, it's a set of guidelines. Some of these guidelines might even conflict with each other. Use your judgment on when they're best followed, and if you're not sure, ask someone who'll be learning from what you write what makes the most sense.
|
|
</p>
|
|
<p class='vspace'></p><h2>Writing a tutorial (most of this is borrowed from various editors over the years)</h2>
|
|
<p>Write in the active voice.
|
|
</p>
|
|
<p class='vspace'></p><p>Write clearly and conversationally, as if the person following your instructions were there in the room with you.
|
|
</p>
|
|
<p class='vspace'></p><p>When giving instruction, write in the second person, so the reader understands that she's the one who'll be doing it.
|
|
</p>
|
|
<p class='vspace'></p><p>Use short, simple sentences rather than compound sentences. It's easier for the reader to digest one instruction at a time.
|
|
</p>
|
|
<p class='vspace'></p><p>Use pictures and schematics rather than just schematics alone. Many electronics hobbyists don't read schematics
|
|
</p>
|
|
<p class='vspace'></p><p>Check your assumptions. Does the reader understand all the concepts you've used in your tutorial? If not, explain them or link to another tutorial that does.
|
|
</p>
|
|
<p class='vspace'></p><p>Explain things conceptually, then lay out instructions on how to use it step-by-step.
|
|
</p>
|
|
<p class='vspace'></p><p>Make your example do one thing well. Don't combine concepts unless it's a tutorial about combining concepts.
|
|
</p>
|
|
<p class='vspace'></p><h2>Writing Example Code</h2>
|
|
<p>Efficiency is not paramount; readability is.
|
|
</p>
|
|
<p class='vspace'></p><p>The most important users of Arduino are beginners and people who don't care about code, but about getting projects done.
|
|
</p>
|
|
<p class='vspace'></p><p>Think generously about people who know less than you about code. Don't think they <em>should</em> understand some technical concept. They don't, and they're not stupid for not understanding. Your code should explain itself, or use comments to do the same. If it needs a complex concept like registers or interrupts or pointers, either explain it or skip it.
|
|
</p>
|
|
<p class='vspace'></p><p>When forced to choose between technically simple and technically efficient, choose the former.
|
|
</p>
|
|
<p class='vspace'></p><p>Introduce concepts only when they are useful and try to minimize the number of new concepts you introduce in each example. For example, at the very beginning, you can explain simple functions with no variable types other than int, nor for consts to define pin numbers. On the other hand, in an intermediate example, you might want to introduce peripheral concepts as they become useful. Concepts like using const ints to define pin numbers, choosing bytes over ints when you don't need more than 0 - 255, etc. are useful, but not central to getting started. So use them sparingly, and explain them when they're new to your lesson plan.
|
|
</p>
|
|
<p class='vspace'></p><p>Put your <code>setup()</code> and your <code>loop()</code> at the beginning of the program. They help beginners to get an overview of the program, since all other functions are called from those two.
|
|
</p>
|
|
<p class='vspace'></p><h3>Commenting Your Code</h3>
|
|
<p>Comment every variable or constant declaration with a description of what the variable does.
|
|
</p>
|
|
<p class='vspace'></p><p>Comment every code block. Do it before the block if possible, so the reader knows what's coming
|
|
</p>
|
|
<p class='vspace'></p><p>Comment every for loop
|
|
</p>
|
|
<p class='vspace'></p><p>Use verbose if statements. For simplicity to the beginning reader, use the block format for everything, i.e. avoid this:
|
|
</p>
|
|
<p class='vspace'></p><pre>
|
|
if (somethingIsTrue) doSomething;
|
|
|
|
</pre>
|
|
<p class='vspace'></p><p>Instead, use this:
|
|
</p><pre>
|
|
if (somethingIsTrue == TRUE) {
|
|
doSomething;
|
|
}
|
|
|
|
</pre>
|
|
<p class='vspace'></p><p>Avoid pointers
|
|
</p>
|
|
<p class='vspace'></p><p>Avoid <code>#defines</code>
|
|
</p>
|
|
<p class='vspace'></p><h3>Variables</h3>
|
|
<p>Avoid single letter variable names. Make them descriptive
|
|
</p>
|
|
<p class='vspace'></p><p>Avoid variable names like <code>val</code> or <code>pin</code>. Be more descriptive, like <code>buttonState</code> or <code>switchPin</code>
|
|
</p>
|
|
<p class='vspace'></p><p>If you want to define pin names and other quantities which won't change, use const ints. They're less messy than #defines, yet still give you a way to teach the difference between a variable and a constant.
|
|
</p>
|
|
<p class='vspace'></p><p>Use the wiring/Processing-style variable types, e.g. boolean,char,byte,int,unsigned int,long,unsigned long,float,double,string,array,void when possible, rather than uint8_t, etc. The former are explained in the documentation, and less terse names.
|
|
</p>
|
|
<p class='vspace'></p><p>Avoid numbering schemes that confuse the user, e.g.:
|
|
</p><pre>
|
|
pin1 = 2
|
|
pin2 = 3
|
|
etc.
|
|
|
|
</pre>
|
|
<p class='vspace'></p><p>If you need to renumber pins, consider using an array, like this:
|
|
</p>
|
|
<p class='vspace'></p><pre>
|
|
int myPins[] = { 2, 7, 6, 5, 4, 3 };
|
|
|
|
</pre>
|
|
<p class='vspace'></p><p>This allows you to refer to the new pin numbers using the array elements, like this:
|
|
</p>
|
|
<p class='vspace'></p><pre>
|
|
digitalWrite(myPins[1], HIGH); // turns on pin 7
|
|
|
|
</pre>
|
|
<p class='vspace'></p><p>It also allows you to turn all the pins on or off in the sequence you want, like this:
|
|
</p>
|
|
<p class='vspace'></p><pre>
|
|
for (int thisPin = 0; thisPin < 6; thisPin++) {
|
|
digitalWrite(myPins[thisPin], HIGH);
|
|
delay(500);
|
|
digitalWrite(myPins[thisPin], LOW);
|
|
delay(500);
|
|
}
|
|
|
|
</pre>
|
|
<p class='vspace'></p><h2>Explain the code at the start</h2>
|
|
<p>Here's a good title block:
|
|
</p>
|
|
<p class='vspace'></p><pre>
|
|
/*
|
|
Sketch title
|
|
|
|
Describe what it does in layman's terms. Refer to the components
|
|
attached to the various pins.
|
|
|
|
The circuit:
|
|
* list the components attached to each input
|
|
* list the components attached to each output
|
|
|
|
Created day month year
|
|
By author's name
|
|
Modified day month year
|
|
By author's name
|
|
|
|
http://url/of/online/tutorial.cc
|
|
|
|
*/
|
|
|
|
</pre><h2>Circuits</h2>
|
|
<p>For digital input switches, the default is to use a pulldown resistor on the switch rather than a pullup. That way, the logic of a switch's interaction makes sense to the non-engineer.
|
|
</p>
|
|
<p class='vspace'></p><p>Keep your circuits simple. For example, bypass capacitors are handy, but most simple inputs will work without them. If a component is incidental, explain it later.
|
|
</p>
|
|
<p class='vspace'></p><p><a class='wikilink' href='index.html'>Reference Home</a>
|
|
</p>
|
|
<p class='vspace'></p><p><em>Corrections, suggestions, and new documentation should be posted to the <a class='urllink' href='http://www.arduino.cc/cgi-bin/yabb2/YaBB.pl?board=swbugs' rel='nofollow'>Forum</a>.</em>
|
|
</p>
|
|
<p class='vspace'></p><p>The text of the Arduino reference is licensed under a
|
|
<a class='urllink' href='http://creativecommons.org/licenses/by-sa/3.0/' rel='nofollow'>Creative Commons Attribution-ShareAlike 3.0 License</a>. Code samples in the reference are released into the public domain.
|
|
</p>
|
|
</div>
|
|
|
|
</div>
|
|
<!--PageFooterFmt-->
|
|
<div id="pagefooter">
|
|
<a href='#'>Edit Page</a> | <a href='#'>Page History</a> | <a href='#' target='_blank'>Printable View</a> | <a href='http://arduino.cc/en/Site/AllRecentChanges'>All Recent Site Changes</a>
|
|
</div>
|
|
<!--/PageFooterFmt-->
|
|
</div>
|
|
</body>
|
|
</html>
|