How to write a great Propeller Object.
Jen J.
Posts: 649
Hello all.
Need some help please. Want to add a page to the http://obex.parallax.com that contains a list of guidelines for writing and submitting a Propeller object. Just a short, simple list (if that is possible).
In your opinion:
• What makes a great Propeller object?
• What kind of information would be most helpful to include in the object's description?
Feel free to make your own list. I look forward to reading your responses. And thank you.
Cheers, JJ
Need some help please. Want to add a page to the http://obex.parallax.com that contains a list of guidelines for writing and submitting a Propeller object. Just a short, simple list (if that is possible).
In your opinion:
• What makes a great Propeller object?
• What kind of information would be most helpful to include in the object's description?
Feel free to make your own list. I look forward to reading your responses. And thank you.
Cheers, JJ
Comments
An initial description of the object at the beginning.
A brief description for each procedure at its beginning
Appropriate naming of variables with a description of its purpose and use
Even line by line comments for complicated code.
Learning by example is very helpful and is made easier by comments, descriptions and meaningful variable naming.
And a·comment to the right·saying that is the output pin. (Explain what the settings are for if someone else might need to change them.)
And perhaps a comment as to what other object files are needed for it to work.
Perhaps baud rate settings at the top as well.
Basically·as much as possible, place all the things which people would change at the top and say what all is needed to get it to work.
A good example of what I am trying to say ... shift registers objects, which can be made to work slowly in Spin AND to bleed with speed in assembly. This approach makes the chip(device) logic very clear to everyone and helps the user understand the PASM code in the advanced object.
These kinds of submissions deserve 5 stars.
Rich
Loads of commenting helps use, as does a good description of what the object is supposed to input / output.
Clear indication of what the variables do is also very helpful.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Cheers,
Simon
www.norfolkhelicopterclub.com
Announcement: To cut costs in the current economic climate, we have switched-off the light at the end of the tunnel.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Propeller Wiki: Share the coolness!
8x8 color 80 Column NTSC Text Object
Safety Tip: Life is as good as YOU think it is!
A clear statement of what the Object is meant for.
A wiring diagram, if applicable.
Decent descriptions of what the variables are and what their limitations might be.
Variable names that are, in themselves, descriptive of their use. (One letter variable names seem a little too succinct for me.)
Almost line by line comments that explain what's happening.
Maybe some idea of how many cogs will get used by the object.
Experts can always strip out the comments if they desire, but methinks having clear explanations of what is going on would make for an excellent learning tool.
Opening up an object only to find it loaded with assembly code and no comments is, from my unworthy newbie standpoint, practically useless. Though I don't expect volunteers to post ideal objects, it seems to me that the objects provided by Parallax to get us started should have more commentary than what's been the norm.
All of this is, of course, IMHO.
Wiring diagram, consistent formatting (using our template) and explanation of the resources used to run the object.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Ken Gracey
Parallax Inc.
Follow me at http://twitter.com/ParallaxKen for some insider news.
I've never seen the template you mention, and it's not on the Propeller Downloads webpage. Where might one find it?
Thanks,
-Phil
A simple demo, add a second one if you want to show all the cool stuff.
Comments are important, they should cover the general program flow and any tricky bits and bobs code wise.
I'm afraid the parallax produced objects fail on commenting in most cases.
Graham
Have a demo (using PST) that utilizes every command in the object
Have EVERY PUB routine commented as to how to operate
Have a large comment at the top that explains how this object should be used
Have PUB routines and variables marked in a way that you can tell what purpose they serve
If in PASM, have instructions on how to incorporate it into SPIN because most don't know PASM.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Check out my new website!!
Use the Propeller icon!!
Follow me on Twitter! Search "Microcontrolled"
Attached is a finished·version of my new DS1307 RTC driver. What do you think·of demo?
I'm not supporting everything that everyone wants but I believe I'm at a nice middle ground where the code is readable and not to hard to understand but doesn't require to much extra work on my end.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Nyamekye,
1. Capitalize the first letter of global variable names. Multi-word names can use multiple caps or underscores: e.g. MaxVelocity or Max_velocity.
2. CONstant names use ALL_CAPS. They're a PITA to type, but it makes their origin crystal clear.
3. Local variables are lower case. Separate multi-word names with underscores if it aids clarity: e.g. max_velocity.
4. Lower case for all keywords, hex vallues, and PASM operators, except for section headings: CON, OBJ, PUB, PRI, DAT.
5. Use hex or binary for constants used in bitwise operations: e.g. a & $ff, not a & 255.
6. Use double-apostrophe comments for method descriptions, so they show up in the doc view.
I typically don't capitalize the names of methods. Sometimes, I precede the names of PRIvate methods with an underscore, though.
One thing I'm learning the hard way is this: if you have multiple assembly language cogs, make liberal use of :local labels. That way you can reuse the names. It would be helpful if the compiler supported SX-style label referencing, though: i.e. global:local.
I don't mean to suggest that everyone should use my notation. But I do mean to convey that whatever notational standards a programmer adopts should be used consistently. It helps the readability of a program.
-Phil
Post Edited (Phil Pilgrim (PhiPi)) : 5/3/2010 9:25:11 PM GMT
A) Clearly commented code that's understandable for an "average" programmer. I see comments to two extremes.
1) A complex line of code will be commented for a 5 year old with little detail (IE: next to a massive line of code for calculating distances between two points on earth it will say "do some math")
2) An average line of code will be commented with so much jargon and/or high level abbreviations (IE a "stamp-experienced propeller-newbie" like me still has to use the propeller manual to decipher the code step by step to figure out what is going on)
I guess I would like to see straightforward comments that are in the "middle of the road" for interpretation. Granted that middle area is pretty wide, but just stay away form the extremes.
As for the structure of objects, as long as they are not a total mess, it's ok that they are not exactly to a template. The propeller tool will help in this regard. Also, I am sure some people code some excellent objects but do not want to waste time to comment them and make demos for "us newbies that need a little help", but how can we expect the propeller to grow if we don't continue to make it easier for others to get on board? Shouldn't an object oriented programming structure make it much easier for someone to learn? The TV object is so easy to use, I had my demo board up and running altered demo code in about 15 minutes
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Andrew Williams
WBA Consulting
WBA-TH1M Sensirion SHT11 Module
Special Olympics Polar Bear Plunge, Mar 20, 2010
It's attached.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Ken Gracey
Parallax Inc.
Follow me at http://twitter.com/ParallaxKen for some insider news.
May I request you add to that document the MIT License.
Another comment is the 80 character width preference. With PCs and printers able to handle much greater than this I now regularly use wider 100-120 character widths and I do not see an issue with this.
General comments...
Unfortunately, it is hard to demand that Objects conform to any standard. Way too often, beginners expect things to be at their level. The OBEX is not necessarily aimed for them to be able to understand the internals of the code, but rather they are·there to be used as Objects. A good object should not require an understanding of the code underneath... but it should be provided with sufficient information to be able to be easily used within one's own code. Therefore, a simple demo program should be included.
Remember, the objects are contributed freely and any imposition of standards will likely mean that it is just too hard or time consuming to publish an object.
Code comments has always been, and·always will be, a hot topic where everyone agrees to disagree.
I like to liberally splash comments throughout my code. It is there primarily for me to remember what I wrote when I come back to look or modify it perhaps years later. That does not mean everyone will understand what my code is doing line by line. However, I try to add many extra comments to my OBEX code and unfortunately that meant that I did not publish a lot of my code initially.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Links to other interesting threads:
· Home of the MultiBladeProps: TriBlade,·RamBlade,·SixBlade, website
· Single Board Computer:·3 Propeller ICs·and a·TriBladeProp board (ZiCog Z80 Emulator)
· Prop Tools under Development or Completed (Index)
· Emulators: CPUs Z80 etc; Micros Altair etc;· Terminals·VT100 etc; (Index) ZiCog (Z80) , MoCog (6809)·
· Prop OS: SphinxOS·, PropDos , PropCmd··· Search the Propeller forums·(uses advanced Google search)
My cruising website is: ·www.bluemagic.biz·· MultiBlade Props: www.cluso.bluemagic.biz
I think the 80-column limit has more to do with the template being designed for publication use than anything else. Having reproduced a number of code listings in Word, I can tell you that when a line runs much past 80 columns, it's a struggle to know how to format it for publication. You want it to be readable, but yet the reader has to be able to cut and paste it into an IDE. For the OBEX, I doubt that it will be that big of a deal. Besides, if someone wants to publish the code, they can always resort to the {CR} trick for formatting purposes.
-Phil
Well said Ray, I was talking about focus earlier and you know it's easy to lose focus when you try to make something that is all things to all people. An object is a useful thing, and yes it should have sufficient information to be easily used with one's code. All else is cream, we like cream, but it's an extra. All the other comments made so far have merit too but let's just set a minimum standard so that we can get more objects into the obex. Saying this I realize too that there are too many variants of the same object such as serial, RTC objects etc and not always in the same category either or with the same naming conventions, what a mess. Any ideas what we can do here?
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
*Peter*
-Phil
Minimum requirements and some standards are what we can hope for. Perhaps we could have a obex team responsible for moderating and possibly categorizing and/or renaming objects. Wouldn't it also be possible for others to add comments that they find useful? This would not be the actual object that is commented though, just in case, but a documented copy used for reference.
my2cents
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
*Peter*
I've commented before that those who seek standards are usually the same people who want to set those standards. But I think that, in this case, Parallax has a legitimate reason for doing both. And, best of all, they're giving us a chance to weigh in on which standards might be useful and what they should be.
-Phil
Post Edited (Phil Pilgrim (PhiPi)) : 5/4/2010 5:53:38 AM GMT
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Powered by enthusiasm
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
*Peter*
To reiterate, although the guidelines might be a list I think it is important that explanations are given for each element, people won't follow them on blind faith and neither should they.
Graham
As a propeller user who is almost out of the newbie stage, I do expect objects published in the OBEX to be in a format that allows me to use them without having to wait until I am at "prop-guru" stage to understand them. However, at the same time, I don't want "gurus" to stop publishing objects because they take up too much of their valuable time.
Anyhow, the idea that was sparked comes from the Beanie icon in the OBEX. Objects created by Parallax have the beanie icon next to them. How about another icon system for objects that fully conform to a "makes everyone happy standard"? In other words, if the object is in the proper format, follows Ken's mentioned template, is commented with detailed comments, includes a clean working demo, and includes a fully commented demo that details the objects functions, etc, etc, give it a special icon in the OBEX.
This doesn't force a standard on anyone submitting objects, but it lets everyone know which ones do conform to a desired standard. Newbies can target the objects with this icon to aid with their learning and if they need an object that doesn't have the icon, they know they will need to do some searching through the forums for the help they may need. Either way, it provides a method for knowing the level at which an object can be considered usable depending on your level of experience/knowledge.
Just for fun, two icons are attached. The one with the crayon would be for "newbie compatible" objects and the one with the pen could be for "some assembly required" (no pun intended)
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Andrew Williams
WBA Consulting
WBA-TH1M Sensirion SHT11 Module
Special Olympics Polar Bear Plunge, Mar 20, 2010
Post Edited (WBA Consulting) : 5/4/2010 7:27:17 PM GMT
I think this is an excellent idea!
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Nyamekye,
I also like the·additional icon idea to show·the object meets some sort of standard.
So far as zillions of objects doing the same thing, I was thinking for at least the display area, perhaps·subdirectories·might be helpful. Like LCD, VGA, TV, or whatever. And perhaps *assume* people do not know what the difference is. Perhaps a short description of what a LCD display is or a link to click on which would say a bit about what LCD displays are. Then same for VGA, and others.
And this I assume is an international audience who would be visiting the OBEX? The words used to describe things - terms used in other countries can be quite different from what is used in the US sometimes.
For example in England the bathroom is called the "loo" and the circuit breaker panel is called the "mains". In Canada their electric company is called "Hydro". (I thought they were talking about their water company when I first heard this term!)
Frankly, I think it would be great if we could adopt something like the Perl POD (plain old documentation) convention for source files. The pod2html converter produces very nice-looking documentation. It would even be possible to convert the Unicode stuff to HTML-embedded GIFs without too much difficulty.
-Phil
An icon or two awarded by Parallax (or someone deputised) could work. But it cannot be left to the OBEX depositor... I wouldn't add one although it may be worthy, and some may add it where it was not worthy.
bill190: Yes, been there and been caught. In Australia Durex is sticky tape, and there are lots of others.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Links to other interesting threads:
· Home of the MultiBladeProps: TriBlade,·RamBlade,·SixBlade, website
· Single Board Computer:·3 Propeller ICs·and a·TriBladeProp board (ZiCog Z80 Emulator)
· Prop Tools under Development or Completed (Index)
· Emulators: CPUs Z80 etc; Micros Altair etc;· Terminals·VT100 etc; (Index) ZiCog (Z80) , MoCog (6809)·
· Prop OS: SphinxOS·, PropDos , PropCmd··· Search the Propeller forums·(uses advanced Google search)
My cruising website is: ·www.bluemagic.biz·· MultiBlade Props: www.cluso.bluemagic.biz
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔