253 lines
13 KiB
HTML
253 lines
13 KiB
HTML
<?xml version="1.0" encoding="utf-8"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns:MadCap="http://www.madcapsoftware.com/Schemas/MadCap.xsd" MadCap:lastBlockDepth="6" MadCap:lastHeight="94" MadCap:lastWidth="853" MadCap:disableMasterStylesheet="true" MadCap:tocPath="PBASIC Language Reference" MadCap:InPreviewMode="false" MadCap:PreloadImages="false" MadCap:RuntimeFileType="Topic" MadCap:TargetType="WebHelp" lang="en-us" xml:lang="en-us" MadCap:PathToHelpSystem="../../../" MadCap:HelpSystemFileName="Default.xml" MadCap:SearchType="Stem">
|
|
<head><title>Elements of PBASIC Style</title>
|
|
<link href="../../SkinSupport/MadCap.css" rel="stylesheet" />
|
|
<link href="../../Resources/Stylesheets/BSE_Help.css" rel="stylesheet" />
|
|
<script src="../../SkinSupport/MadCapAll.js" type="text/javascript">
|
|
</script>
|
|
</head>
|
|
<body>
|
|
<div class="MCBreadcrumbsBox_0"><span class="MCBreadcrumbsPrefix">You are here: </span><a class="MCBreadcrumbsLink" href="AlphaRef.htm">PBASIC Language Reference</a><span class="MCBreadcrumbsDivider"> > </span><span class="MCBreadcrumbs">Elements of PBASIC Style</span>
|
|
</div>
|
|
<h1>Elements of PBASIC Style</h1>
|
|
<h2>INTRODUCTION</h2>
|
|
<p class="PlainText">Like most versions of the BASIC programming language, PBASIC is very forgiving
|
|
and the compiler enforces no particular formatting style. As long as the source
|
|
code is syntactically correct, it will compile and download to the BASIC Stamp
|
|
without trouble.</p>
|
|
<p class="PlainText">Why, then, would one suggest a specific style for PBASIC? Consider this: Over
|
|
three million BASIC Stamp modules have been sold and there are several thousand
|
|
members that participate in the
|
|
<a href="http://forums.parallax.com/forums/default.aspx" target="_blank" title="Open Parallax Forums in new window" alt="Open Parallax Forums in new window">Parallax online forums</a>.
|
|
This makes it highly likely that you'll be sharing your PBASIC code
|
|
with someone, if not co-developing a BASIC Stamp project. Writing code in an
|
|
organized, predictable manner will save you -- and your potential colleagues --
|
|
a lot of time; in analysis, in troubleshooting and especially when you return to
|
|
a project after a long break.</p>
|
|
<p class="PlainText">The style guidelines presented here are just that: <i>guidelines</i>. They have
|
|
been developed from style guidelines used by professional programmers using other
|
|
high-level languages such as Visual Basic<sup>®</sup>, C/C++, and Java™.
|
|
Use these guidelines as-is, or modify them to suit your individual needs. The key
|
|
is selecting a style the works well for you or your organization, and then
|
|
sticking to it.</p>
|
|
<h2>PBASIC Style Guidelines</h2>
|
|
<h3>1. Do It Right The First Time</h3>
|
|
<p class="PlainText">Many programmers, especially new ones, fall into the "<i>I'll knock it out now
|
|
and fix it later.</i>" trap. Invariably, the "<i>fix it later</i>" part never
|
|
happens and sloppy code makes its way into production projects. If you don't
|
|
have time to do it right, when will you find time to do it again?</p>
|
|
<p class="PlainText">Start clean and you'll be less likely to introduce errors in your code. And
|
|
if errors do pop up, clean and organized formatting will make them easier to find
|
|
and fix.</p>
|
|
<h3>2. Be Organized and Consistent</h3>
|
|
<p class="PlainText">Using a blank program template will help you organize your programs and establish
|
|
a consistent presentation.</p>
|
|
<h3>3. Use Meaningful Names</h3>
|
|
<p class="PlainText">Be verbose when naming constants, variables and program labels. The compiler will
|
|
allow names up to 32 characters long. Using meaningful names will reduce the
|
|
number of comments and make your programs easier to read, debug and maintain.</p>
|
|
<h3>4. Naming I/O Pins</h3>
|
|
<p class="PlainText">BASIC Stamp I/O pins are a special case as various elements of the PBASIC language
|
|
require a pin to be constant value, an input variable or an output variable. To
|
|
prevent redundant definitions, use the PIN type.</p>
|
|
<img src="../../graphics/bs2all_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
HeaterCtrl PIN 15
|
|
</pre>
|
|
<p class="PlainText">Since connections don't change during the program run, I/O pins are named like
|
|
constants using mixed-case, beginning with an uppercase letter.</p>
|
|
<h3>5. Naming Constants</h3>
|
|
<p class="PlainText">Begin constant names with an uppercase letter and use mixed case, using uppercase
|
|
letters at the beginning of new words within the name.</p>
|
|
<img src="../../graphics/bs1_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
SYMBOL AlarmCode = 25
|
|
</pre>
|
|
<img src="../../graphics/bs2all_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
AlarmCode CON 25
|
|
</pre>
|
|
<h3>6. Naming Variables</h3>
|
|
<p class="PlainText">Begin variable names with a lowercase letter and use mixed case, using uppercase
|
|
letters at the beginning of new words within the name.</p>
|
|
<p class="PlainText">BS1: Avoid using W0 (B0 and B1) so that bit variables (Bit0..Bit15) are
|
|
available for use in your programs. Bit variables 0..15 overlay W0, so the use
|
|
of W0 may cause undesired effects.</p>
|
|
<img src="../../graphics/bs1_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
SYMBOL waterLevel = W1
|
|
</pre>
|
|
<p class="PlainText">BS2: Avoid the use of internal variable names (such as B0 or W1) in your
|
|
programs. Allow the compiler to automatically assign RAM space by declaring a
|
|
variable of specific type.</p>
|
|
<img src="../../graphics/bs2all_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
waterLevel VAR Word
|
|
</pre>
|
|
<h3>7. Variable Type Declarations</h3>
|
|
<p class="PlainText">When using the BS1, variable type is declared by aliasing the SYMBOL name to an
|
|
internal variable of a specific size.</p>
|
|
<img src="../../graphics/bs1_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
SYMBOL status = Bit0
|
|
SYMBOL ovenTmp = B2
|
|
SYMBOL rndVal = W2
|
|
</pre>
|
|
<p class="PlainText">For the BS2, variable types should be in mixed-case and start with an
|
|
uppercase letter.</p>
|
|
<img src="../../graphics/bs2all_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
status VAR Bit
|
|
counter VAR Nib
|
|
ovenTmp VAR Byte
|
|
rndVal VAR Word
|
|
</pre>
|
|
<p class="PlainText">Conserve BASIC Stamp user RAM by declaring the variable type required to hold
|
|
the expected values of the variable. </p>
|
|
<img src="../../graphics/bs1_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
SYMBOL bitVal = BIT0 ' 0 - 1
|
|
SYMBOL byteVal = B2 ' 0 - 255
|
|
SYMBOL wordVal = W2 ' 0 - 65535
|
|
</pre>
|
|
<img src="../../graphics/bs2all_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
bitValue VAR Bit ' 0 - 1
|
|
nibValue VAR Nib ' 0 - 15
|
|
byteValue VAR Byte ' 0 - 255
|
|
wordValue VAR Word ' 0 - 65535 </pre>
|
|
<h3>8. Program Labels</h3>
|
|
<p class="PlainText">Begin program labels with an uppercase letter, used mixed case, separate words
|
|
within the label with an underscore character and begin new words with a number
|
|
or uppercase letter. Labels should be preceded by at least one blank line, begin
|
|
in column 1 and must be terminated with a colon (except after GOTO and THEN
|
|
[in classic PBASIC] where they appear at the end of the line and without a colon).</p>
|
|
<img src="../../graphics/bsall_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
Print_String:
|
|
READ eeAddr, char
|
|
IF char = 0 THEN Print_Done
|
|
DEBUG char
|
|
eeAddr = eeAddr + 1
|
|
GOTO Print_String
|
|
|
|
Print_Done:
|
|
RETURN
|
|
</pre>
|
|
<h3>9. PBASIC Keywords</h3>
|
|
<p class="PlainText">All PBASIC language keywords, including SYMBOL, CON, VAR, PIN and serial/debugging
|
|
format modifiers (DEC, HEX, BIN) and constants (CR, LF) should be uppercase. (Although PBASIC
|
|
is not case-sensitive, the BASIC Stamp Editor's Syntax Highlighting feature will automatically make
|
|
these keywords all caps</p>
|
|
<img src="../../graphics/bsall_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
Main:
|
|
DEBUG "BASIC Stamp", CR
|
|
END
|
|
</pre>
|
|
<h3>10. Indent Nested Code</h3>
|
|
<p class="PlainText">Nesting blocks of code improves readability and helps reduce the introduction of
|
|
errors. Indenting each level with two spaces is recommended to make the code
|
|
readable without taking up too much space.</p>
|
|
<p class="PlainText"><b>Note:</b> <![CDATA[ ]]><i>The dots are used to illustrate the level of nesting and are
|
|
<b>not</b> a part of the code.</i></p>
|
|
<img src="../../graphics/bs1_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
Main:
|
|
..FOR testLoop = 1 TO 10
|
|
....IF checkLevel >= Threshold THEN LED_Okay
|
|
....lowLevel = lowLevel + 1
|
|
....GOTO Loop_Delay
|
|
|
|
LED_Okay:
|
|
....LEDokay = IsOn
|
|
|
|
Loop_Delay:
|
|
....PAUSE 100
|
|
..NEXT
|
|
..IF testMode = Yes THEN Main
|
|
</pre>
|
|
<img src="../../graphics/bs2all_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
Main:
|
|
..DO
|
|
....FOR testLoop = 1 TO 10
|
|
......IF (checkLevel < Threshold) THEN
|
|
........lowLevel = lowLevel + 1
|
|
......ELSE
|
|
........LEDokay = IsOn
|
|
......ENDIF
|
|
......PAUSE 100
|
|
....NEXT
|
|
..LOOP WHILE (testMode = Yes)
|
|
</pre>
|
|
<h3>11. Condition Statements</h3>
|
|
<p class="PlainText">Enclose condition statements in parentheses for clarity (BS2 only - parenthesis
|
|
are not allowed when using the BS1).</p>
|
|
<img src="../../graphics/bs2all_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
Check_Temp:
|
|
IF (indoorTemp >= setPoint) THEN
|
|
AcCtrl = IsOn
|
|
ELSE
|
|
lowLevel = lowLevel + 1
|
|
ENDIF
|
|
</pre><pre class="BScode" xml:space="preserve">
|
|
Fill_Water_Tank:
|
|
DO WHILE (waterLevel = IsLow)
|
|
TankFill = IsOn
|
|
PAUSE 250
|
|
LOOP
|
|
</pre><pre class="BScode" xml:space="preserve">
|
|
Get_Delay:
|
|
DO
|
|
DEBUG HOME, "Enter time (5 - 30)... ", CLREOL
|
|
DEBUGIN DEC2 tmDelay
|
|
LOOP UNTIL ((tmDelay >= 5) AND (tmDelay =< 30))
|
|
</pre>
|
|
<h3>12. Be Generous With White Space</h3>
|
|
<p class="PlainText">White space (spaces and blank lines) does not affect compiler performance or BASIC
|
|
Stamp execution speed, so be generous with it to make listings easier to read. Allow at least one blank line before program labels (two blanks
|
|
lines before a subroutine label is recommended). Separate items in a parameter list
|
|
with a space.</p>
|
|
<img src="../../graphics/bs2all_inline.gif" border="0" alt="" /><pre class="BScode" xml:space="preserve">
|
|
Main:
|
|
DO
|
|
ON task GOSUB Update_Motors, Scan_IR, Close_Gripper
|
|
LOOP
|
|
|
|
Update_Motors:
|
|
PULSOUT MtrLeft, leftSpeed
|
|
PULSOUT MtrRight, rightSpeed
|
|
PAUSE 20
|
|
task = (task + 1) // NumTasks
|
|
RETURN
|
|
</pre>
|
|
<img src="../../graphics/bs2all_inline.gif" border="0" alt="" />
|
|
<p class="PlainText">An exception to this guideline is with the bits parameter used with SHIFTIN
|
|
and SHIFTOUT, the REP modifier for DEBUG and SEROUT, and the byte count and
|
|
terminating byte value for SERIN. In these cases, format without spaces.</p><pre class="BScode" xml:space="preserve">
|
|
SHIFTIN A2Ddata, A2Dclock, MSBPost, [result\9]
|
|
</pre><pre class="BScode" xml:space="preserve">
|
|
DEBUG REP "*"\25, CR
|
|
</pre><pre class="BScode" xml:space="preserve">
|
|
SERIN IRbSIO, IRbBaud, [buffer\8\255]
|
|
</pre>
|
|
<div class="Col2">
|
|
<div class="MasterFoot">
|
|
<p MadCap:conditions="BSEconditions.BSEWebHelp (Primary)-INCLUDE"><a href="../../HomeTopics/HomePage.htm">Go to Welcome page</a>
|
|
</p>
|
|
</div>
|
|
</div>
|
|
<div class="Col2">
|
|
<div class="MasterFoot">
|
|
<p style="text-align: right;"><span class="ContactInfoProjectName">BASIC Stamp Help</span> <![CDATA[ ]]><span class="ContactInfoVersion#">Version 2.5.4</span> <![CDATA[ ]]></p>
|
|
<p style="text-align: right;">Copyright © <span class="ContactInfoCompanyName">Parallax Inc.</span></p>
|
|
<p style="text-align: right;"><span class="SystemShortDate">8/8/2012</span>
|
|
</p>
|
|
</div>
|
|
</div>
|
|
<script type="text/javascript">/* <![CDATA[ */
|
|
|
|
var _gaq = _gaq || [];
|
|
_gaq.push(['_setAccount', 'UA-285614-1']);
|
|
_gaq.push(['_trackPageview']);
|
|
|
|
(function() {
|
|
var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true;
|
|
ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js';
|
|
var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s);
|
|
})();
|
|
|
|
/* ]]> */</script>
|
|
<script type="text/javascript" src="../../SkinSupport/MadCapBodyEnd.js">
|
|
</script>
|
|
</body>
|
|
</html> |