Initial commit after migrating repo and assuring the product launches
This commit is contained in:
@ -0,0 +1,253 @@
|
||||
<?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>
|
Reference in New Issue
Block a user