Help create the Spin Standard Library!
Brett Weir
Posts: 288
A big focus of PropellerIDE is to make Spin a more compelling choice for Propeller development. With that in mind, I have recently started reworking the Spin library bundled with PropellerIDE.
Objective
I want to create a library similar in nature to the LameStation SDK, but useful for any kind of Propeller development. Here's why:
Contributing
This is a big job, and I can't do it by myself. Here's how you can help.
Important Links
Don't be shy!
Your contributions will help ensure that there is a place for Spin in Parallax products for years to come.
If you love this fun, little language, and want to make sure it lives on forever, help us make a stellar standard library that shows off everything Spin is capable of.
Objective
I want to create a library similar in nature to the LameStation SDK, but useful for any kind of Propeller development. Here's why:
- With a consistent style and organization, experience with one object informs the use of many others.
- With few, well-known objects, it is easy to determine the right object to use for a given job (for example, the current library has 3 different floating point libraries and I have no idea which one to use)
- With well-defined interfaces, modules can be upgraded with new IDE releases while minimizing impact to existing code, or swapped out for similar objects.
Contributing
This is a big job, and I can't do it by myself. Here's how you can help.
- Suggestions/code submissions of objects to incorporate.
- Review/explanation of existing objects to see which are actually useful and/or appropriate for a basic library.
- Comparison of similar objects for inclusion (FullDuplexSerial vs. Parallax Serial Terminal, or both, for example).
Important Links
Don't be shy!
Your contributions will help ensure that there is a place for Spin in Parallax products for years to come.
If you love this fun, little language, and want to make sure it lives on forever, help us make a stellar standard library that shows off everything Spin is capable of.
Comments
I agree with most of your style recommendations, except for:
2. The first character of global variables should be capitalized; local variables, lower-case.
3. The use of CamelCase or Underline_style should be optional. Both are equally readable.
4. I like a leading underline (sometimes) for PRIvate method _names. It's a useful sigilt to distinguish from PUBlic method calls.
But those are just my personal preferences that I don't even always follow. More generally, why bother enforcing style at all? Such dictums only irritate people who have their own ways of coding. So long as a program is readable, what difference does it make?
-Phil
The library delivered with the PropTool is full of useful stuff, but sadly quite confusing for a beginner. The best stuff is from @Chip, but sadly he likes 2 letter label/constant names. His video drivers would be way more understandable with meaningful long descriptive names.
Sadly they aren't, and all the other guys like baggers and potatohead and whoever else kept that short naming thing for constants and labels doing their video stuff.
No way to grook that for a beginner. So doing a rework of that library is a honorable task. Sisyphus comes into my mind for some reason.
Some years ago I started a standard library by using the wonderful spin documenter from @PhiPi. Something like Doxigen for spin, creating nice html docs out of the spin source.
So I reworked Kye's FAT_Engine for example. But a couple of month later he came out with a new version and all my work was useless.
Now with Parallax using GIT things might change. But if changes do not make it upstream, all effort is useless.
Sadly,
Mike
In the Gold Standard, IIRC, the underline style was used for constants. All variables began with a lowercase letter. Method names were capitalized.
IMO, it's important to differentiate between variable names and method names.
BTW, programming in Spin/PASM is pretty much my day job these days. I've been trying to learn to use the Arduino and C. I remember initially being irritated to have to learn Spin in order to use the Propeller but now I find C very irritating to use. All those unneeded characters which are redundant if one uses proper (two spaces) indentation.
Style is arbitrary. Consistency is what's important. Programmers spend vastly more of their time reading code than writing it. I want it to be as easy as possible to pick up a new object and use it. Without consistency, every object is a new headache, a new puzzle to unravel. This project reduces the barriers to entry for new users.
Sisyphus absolutely comes to mind, but I have no intention of working against contributors.
That's why I will only be incorporating new objects that follow the style guide, or are stable enough that it doesn't matter whether the original creator plays ball or not. Many library objects may be only loosely based on the original objects, with no effort made to keep track of the upstream. Such a strategy is not ideal, but if community participation does fall flat, this is the only way to do it without losing my mind.
But that's why I am reaching out. If developers want to participate and have their objects included with every download of PropellerIDE, they can work with me to do it. With GitHub, developers can update their objects in place in the repository, so the Spin standard library can and should be the new upstream for anyone serious about contributing.
If we all work together, we can see Spin become a serious contender to C in Parallax Education programs, which would mean more investment, more development, more user base, more everything. So why wouldn't Spin developers want to participate?
A project like this benefits the entire Spin community, so let's make it happen.
A few things come to mind...
The gold standard was a great idea but the only object done was FullDuplexSerial. It was done without consultation so the couple of changes that I had done and posted in obex wasn't included.
There have been many discussions about making it possible to have a mini operating system and using the top of hub for rendezvous locations. On every instance, no one was interested in creating a standard except a small number of us. With the total lack of enthusiasm and support, a few of us did our own thing.
Now many of those no longer frequent the forums.
I truly wish you well with your endeavours but please don't expect wonders here. It's been tried before without success
I think it will fail because:
0) I always thought OBEX was the "Standard Library". It's the first place I look for anything I need for the Propeller. It's pretty well static as any any standard library should be.
1) This idea has been tried before. The "Gold Standard Object" intitiative. It flopped.
2) Fixing up formatting and such of someone else's work is basically forking it. A bad idea unless the original authors are on board. Any bug fixes or new features they add to their project/object won't make it into the standard fork.
3) It's "busy work" with no functional gain that nobody really wants to do.
Basically all such standards for code contributions to OBEX should have been in place from the beginning. Then the "standard" would be done already.
What I would like to see is a sort of package manager as used in Python or Node.js where a simple command like "ppm install f32" (Propeller Package Manager) installed the f32 object into my project from OBEX and away I go. What do I care how it is written or formatted? Of course the Prop Tool or other IDEs would have a GUI to do this.
Now for the positive suggestion:
Work on such a standard library for the PII. The PII is a clean slate. Many of those good things in OBEX and elsewhere will need to be ported to the PII. Whilst that major work is going on standards for formatting and whatever can be applied. It's quite likely that the original authors of those objects won't be around or so inclined to do this work so a fork is justified. Many people will be motivated to take their favorite thing from OBEX and "fix it for the PII". It's not just "busy work" it has a functional outcome.
Arrange that this all happens in a git (github) powered OBEX/Standard Library for the PII
I was quite frustrated in my early Spin days that the code I found in OBEX was not more self explanatory, and more logically structured. A lot of it is just hacked together, it seems. On the other hand, I guess a lot would say that my code has too much overhead in it.
Not long ago I was advised by the Forum not to use the |<n operator, but instead 1<<n, even if it is slightly less efficient - because with the latter syntax 'anyone' will understand it. I think that was a good advice and a good attitude to promote.
I suspect it will be hard to make the majority follow any kind of strict standard, as it is mostly the 'newbies' who benefits from it, but would help make Spin survive. I hate all that void() { } etc. of the alternative.
Erlend
JS is full of () and {} and ;
Now all my JS code is very nicely and consistently formatted. How did that happen? Well for JS there are many tools called "linters", jslint, jshint, eslint and so on. Most of them can be run from the editor as I type my code. The linters get things underlined with red squigglies if they think I am straying from correct style. I fix it as I type.
Those () and {} and ; make all this possible. I'm guessing its not so easy for a language with white space indenting and no formal specification.
Without such tools it's a huge and boring task to enforce any "house style."
Now, I'm not sure why a "house style" is even needed. A thousand people have created a thousand useful objects for Spin, in their own way, as long as it works as advertised I'm happy. What do I care how they wrote it. Same as if I use "printf" or whatever in C.
For educational examples certainly there is a need for clarity and consistency. But converting all of OBEX to be so is not realistic.
Re: little nubby variable names
Noted.
I actually caught some flack for verbose comments and more aggressive code section delineation, so I quit. Strange world we live in sometimes.
There is only one style I consider important and that is more and better comments. Code can be documentation. Good comments help a lot with that.
A long while back, I went through graphics_demo.spin and commented the Smile out of it, and added a few helper methods. Few people have used the cooler stuff that code does. The tv, vga, and tvtext.spin drivers can actually do a lot more than it appears.
I thought on reason for that was lack of docs. The HYDRA book helped, as did comments.
But, somehow that code still goes underused. I do however get more requests for help from people who have read the commented code, so there is that, and it's good.
Is it lack of interest? Is it lack of general video and graphics info, definitions, how to info?
Heck, if I know. But I do know more comments is better.
While making this library, why not comment the code more? Pick it apart and share what you learn? The originals are still there, and people can work with either one, and many people are gone or have just moved on, but the code is still there.
I'm working on some driver related things for P2 and will consider more comments, better comments, and a least comments that expand on those little variable name nubs.
The thing is, I personally dislike long var names. Short is good, once the name gets mapped to an idea. So, I'll split the middle, keep short names, but comment them. Fair?
People write how and what they write. When we get in the way of that, we don't get as much code. I personally have not put code out there in the past for concerns over style, etc...
But, I'm past that now. Just put it out there, no worries.
I think it's much better to comment and document .
If you have to prioritize... which comes first?
Consistency, or understanding?
I'll take the latter every time. The former makes life a bit easier, but not that much easier.
YMMV, of course!
When I worked through Chip's TV.spin long ago, I printed it out, then started reading and annotating. Did a lot of looking up of video concepts, and a lot of tests by changing the code and looking at output with a TV and scope.
IMHO, how to do that is an important skill. The code is a great document itself, but one must couple that with subject matter learning too, or it won't make much sense.
That cycle is currently repeating with P2 video. New concepts in play. I've got a driver printed out, am testing, etc... all over again. Chip will put the bare nubs out there. It's enough to go forward and it's enough to grok how, what, and why, but you gotta work for it.
The term 'herding cats' springs to mind.
Sandy
Here's where I disagree. I think long and descriptive variable and function/method names are a good thing. Very good. Long enough that comments on the variables become redundant and are therefore deleted. To make this reasonable though requires using an editor with autocomplete, which we finally have with PropellerIDE.
More seriously people change their style as their experience grows. Or they don't worry about it much and whatever comes out that day is OK, was it 4 space tabs or 8, ah never mind.
For example, that urge for copious comments soon fades when you realize that comments are lies. They are traps waiting for you. Always out of date and incorrect. As an author you tire of having to read, re-reread and adjust your comments every time you tweak your code or refactor it some way.
Naming things is the hardest problem in computer science. Names are also lies and traps.
That "int32TurnipCounter" may have been a 64 bit counter of any kind of vegetable for years but no one wanted to change it because it means editing 20 modules. And then you'd have to fix the documentation to reflect that change.
Now, maybe I haven't been clear, but I don't think what I am asking for is so far-fetched. So far, there haven't been any responses in the spirit of the original post. So to reiterate, this is what I am asking for:
So with all being said above about naming conventions a better compiler would be helpful.
Your goal of a "Standard Library" is great but will run the propeller chip out of memory because you are including everything.
Someone Please tell me I'm WRong on this!!!
FYI: I have programmed in many languages and I love SPIN!!! It needs a few more functions but all and all it is pretty good for micro control.
PropellerIDE uses OpenSpin which does include support for basic pre-processor options such as #ifdef and #ifndef
https://github.com/parallaxinc/OpenSpin/wiki/Preprocessor
Unused method removal is close to being available in OpenSpin but I have not released a version of PropellerIDE that includes it.
Even so, I want to keep core objects as small as possible, with a focus on smaller APIs and using nested objects instead of large monolithic objects wherever possible. I have had good luck with this strategy on the LameStation SDK, where the single largest consumer of RAM in the average LameStation game is game content.
Take FrappyBard. The entire game, including 7 core LameStation libraries and game content, is 10kB.
https://github.com/lamestation/lamestation-sdk/blob/master/games/FrappyBard/FrappyBard.spin
It's possible to do a lot in the little space on the Propeller.
-Phil
IMHO it is best to have an easy to understand object rather than dictate standards. Long meaningful names do not always equate to short names with good comments.
Here's what I'm looking for:
Off the top of your heads, do you guys have any suggestions for any of these? Can you think of any I haven't listed here that should be covered by this library?
Readable objects are important, with descriptive variable and function names when possible.
Also important are the demos that go with those objects.
Frustrating is when I open a demo for a spin object and it has outputs to TV or LCD screens, which seems silly, as I have a nice usb connection and serial terminal ready to go, already hooked up. Of course demos for those things would output to them, but not ping or float32 demos, right?
Demos that have little or no comments as to what they are doing and why are also frustrating, or no pin definition as a constant. Demo's are where the comments need to be most verbose, as that is where the newbie learns.
There has definitely been an overreliance on video objects in the demo code. Reducing the complexity and "time-to-run" of examples is another target I have for this rework.
I have done 2 LCD routines, one for the Nokia 5110 mono and one for what they call the 5110 color although its nothing like the 5110 interface. Most of my code is well documented although I don't tend to use long names. There are demo programs for these. Since both these LCDs are cheap on eBay, they make good little displays.
If you use FullDuplexSerial (FDX) can you please add the few mods I did - in the obex as FullDuplexSerial_rr004? - buffer sizes can be changed by powers of 2. Cant recall the other tiny bits, but they are commented clearly what I have done.
Another good object is the multiple serial driver - cannot recall the name but I think Tracy Allen was involved. I have never looked/used it, but the discussions have been good on this driver.
I also have a pair of 1pin drivers for composite monochrome TV and PS2 keyboard (obex under debug). On the thread there are diagrams of how to simple connect these with a few resistors. FYI the TV only requires 1 series resistor between ~100R-1K.
As for SD, you cannot go past Kye's FAT driver. I have split this into two sections, the spin functions and the PASM driver. I have added a few more calls to the spin code. I have folded the PASM code to reduce the size somewhat, but its more of a black box that just handles FAT16/32 raw access, plus rebooting. I use it in my PropOS, which BTW I believe is well documented.
-Phil