Style Guide for Spin and PASM

Alexander (Sandy) Hapgood

I was looking for some information on how spin files are laid out and some conventions for formatting code when I came across Style_Guide_for_Print.spin. I'm not sure where I found it but, at the top, it states "This is the Parallax Propeller Object Style Guide for objects intended for publication in print (magazine articles, for example)".

I'm not advocating anything with this post. It's just some information I found and would like to pass on.

Hopefully people will find the files useful. Let me know if you spot any errors.

Sandy

EDITS
Version 1.00 of my style guide is attached
The original document produced by Parallax, Style_Guide_for_Print.spin, is also attached.

Additional material:
- Parallax Gold Standard.

Duane Degn

Thanks for the files. I haven't looked at them yet but I do plan to.

While I'm not so concerned about how code looks in publications, it would be nice if people followed some conventions when writing Spin and PASM.

I try to follow the Gold Standard myself, and I am advocating others do so (not that I expect my advocacy will mean much).

I know it's a personal flaw, but I have a hard time looking at code that doesn't follow the GS and I end up spending more time than I'd like reformatting code from the OBEX and forum (maybe beggars can't be choosers but that doesn't mean beggars can't whine).

Heater.

Oh boy.

After the carnage that results from the language wars the survivors then proceed to fight to the death over formatting standards in the victorious language.

It's rather like what happens when countries get independence from their colonial masters, they immediately have a civil war.

What I have learned is:

1) When contributing to an existing project do what they do. No matter how much you hate it it's better the project as a whole is consistent in its formatting.

2) Never go round reformatting code just to make it look nice for yourself. That causes real problems if you ever have to compare new versions to old versions to see what changed. Like, why do I have this new bug that I did not have before, what changed? Let's run them though diff. Oh s**t every line has changed!

3) Never put comments in your code. If they are correct when you write it they are soon wrong when you change it.

Aside: One of the above is a "half joke".

jazzed

Heater. wrote: »

1) When contributing to an existing project do what they do. No matter how much you hate it it's better the project as a whole is consistent in its formatting.

2) Never go round reformatting code just to make it look nice for yourself. That causes real problems if you ever have to compare new versions to old versions to see what changed. Like, why do I have this new bug that I did not have before, what changed? Let's run them though diff. Oh s**t every line has changed!

3) Never put comments in your code. If they are correct when you write it they are soon wrong when you change it.

+3

Caveat 3: If comments are correct when you write them they are soon wrong if "anyone" changes the code.

The Parallax gold standard is fine, but a little over-bearing with "capitalized method names" (not that the compiler cares) and the number of spaces for an indent. Tabs should never be used of course

Alexander (Sandy) Hapgood

Heater. wrote: »

3) Never put comments in your code. If they are correct when you write it they are soon wrong when you change it.

I get it but if you're careful when naming your variables the code will be much easier to read and will reduce the number of comments required. Not much point in commenting what the variable ItemNum holds in a loop that steps through an array of variables. Using single letters like i is efficient from a typing and space point of view but, in the long term, not very understandable. X and Y can be used when positioning cursors but I can never remember if X refers to columns or rows so I tend toward Col and Row.

The longest name I could find in the Propeller Reserved Words List ( excluding conditions ) is only 9 characters long so you don't always have to use the full 30 characters to make your code readable.

Having said all that there are cases when I might be tempted to use i but only for really tight loops that are only a couple of lines long and where the code makes the value of i clear. I use Temp quite a bit in the same situations but always make sure that Temp is truly temporary. Hmmm, maybe variables like i and Temp could be all lowercase and that would signify their temporary nature.

Sandy

Alexander (Sandy) Hapgood

I learned something! Not all constants in spin are constant.

The constants that are prefixed with an underscore ( _clkfreq, _clkmode, _free, _stack and _xinfreq ) are 'one-time settable" constants.

User defined constants that are prefixed with an underscore might be interpreted by some people as 'one-time settable' so best to use ALL_CAPS which will stand out just as well as bold face.


Sandy

Phil Pilgrim (PhiPi)

ALL constants are "one-time-settable." IOW, you can't redefine them once you've defined them the first time. The only difference between _clkmode, say, and MY_CONSTANT is that the compiler ascribes special meaning to the former and uses it to preset the system clock, so the programmer does not have to do it explicitly. Other than that, the two are just numbers that can be used later in the program.

-Phil

Alexander (Sandy) Hapgood

Phil Pilgrim (PhiPi) wrote: »

ALL constants are "one-time-settable." IOW, you can't redefine them once you've defined them the first time. The only difference between _clkmode, say, and MY_CONSTANT is that the compiler ascribes special meaning to the former and uses it to preset the system clock, so the programmer does not have to do it explicitly. Other than that, the two are just numbers that can be used later in the program.

-Phil

Given your explanation and the fact that _clkmode and _xinfreq are being set in a CON block I can see how that works now.


Thanks,
Sandy

Alexander (Sandy) Hapgood

I've modified FullDuplexSerial.spin to suit my style guide. if you use the spin tool to create binary files for objFullDuplexSerial_v1.22.spin and FullDuplexSerial.spin and then use fc to compare the file contents a match is reported. That and the testing I've done leads me to believe the two files produce identical binary output.

Everything I'm doing here is for personal consumption but I'd like to know what the etiquette is for making changes to existing files. I've kept mention of the original authors in the files. Is that adequate?

Sandy

EDIT
Replaced both files with v1.23

LoopyByteloose

I am sure you figured out that Parallax made most of the style decisions in Spin quite obvious.

On the other hand, PASM is tucked away in the DATA section and is far less obvious on what is what and what goes where.

The Org 0 and FIt 496 usually frame code that is compile to go directly into a Cog, other items are destined for HubRam.

Alexander (Sandy) Hapgood

Loopy; Thanks for the reminder about org and fit, I've updated the style guide in post #1 and the full duplex serial files in post #10

Version control is something that I'm looking at now. Draft filenames will be prefixed with _YYYY_MM_DD until they become final versions. The initial release will be v1.00 with subsequent, minor, releases being v1.01, v1.02, etc. Major revisions will increment the major release number by one and zero the minor release number ( v1.02, v1.03, v2.00 ).

Sandy

Alexander (Sandy) Hapgood

Why I chose 80 columns as the width for code. My wife had a look at what I was doing one day and said 'you need a bigger monitor'. She's a good girl.

She went out a bought me an LG wide screen monitor that I'm able to use as a second monitor in Windows. The LG is configured in portrait mode. When I adjust the font size in the spin tool to a size that's comfortable to read, it works out to be 80 columns with a small margin on the right side. That font size gets me 76 lines of code in the editor window. It's awesome.

I have the spin tool up on the LG monitor and File Manager up on the laptop monitor.

80 columns is also good if you want to print code on 8.5 X 11 paper. I used to do that a lot before I got the LG but now I can see more on the LG than I can on a sheet of paper so I don't have to print at all now.

Sandy

Alexander (Sandy) Hapgood

I just revised the style guide in post #1. I'll review it over the next couple of days and maybe make it a proper first release.

Sandy