While rummaging through folders on my computer, I found another idea for an icon for objects that meet the "makes everyone happy" standard. Implies that the object is ready to teach the user.
Anyhow, I think an icon approach that links to the published "makes everyone happy" standard should be looked at. Also, you could use a "qualification class" system within that. In other words:
Class 1 Object = Meets all desired requirements (comments, docs, full demo, etc)
Class 2 Object = Meets minimum requirements and has a complete demo.
Class 3 Object = Meets Parallax minimum requirements for objects.
What I'd really like to see is the basic objects provided by Parallax be upgraded to be exemplars of great object style. For example, who can tell me where to find the definition of the basepin parameter that is passed to the VGA_Text object? It would seem that this should be easy to find, but it's not. What say you Parallax?
I think, the question is, how can Parallax HELP people to bring in great objects. If you just ORDER high standards you will not get too much objects any more.
Most objects have not been made for obex but for a specific project of the autor. So the informations/hints must be present at the very early stage of the development of the object. So it would be great, if the PropTool and BST would provide·a template with all the hints which arealready have been mentioned above. For example in the CONstant section the names could be written in capitals automaticly. Or there could be a comment headline in the template: limits of the object. Some help to draw circuits would be nice. It is possible with the character set but it is not done very easily.
I wonder, if it was possible to bring an object into template format after it has been written, because I often do a lot of copying from different sources or I start from an existing example.
Of course once a year there is the big prize for the top object that was entered......
I wonder, if it was possible to bring an object into template format after it has been written, because I often do a lot of copying from different sources or I start from an existing example.
bst can do templates. Check out IDE Preferences->IDE Preferences->New File Template Directory.
Drop your spin files in there and they get added as templates in the Ctrl+N New menu.
If someone comes up with an absolute be-all end-all stonking great template I can easily include it compressed and compiled into bst like the PropBasic template is.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
"Are you suggesting coconuts migrate?"
Ken Gracey (Parallax) said...
I prefer objects that include a demo using Parallax Serial Terminal. Easy to use, everybody has it. . . a demo should be simple and able to run with minimal setup and configuration.
Wiring diagram, consistent formatting (using our template) and explanation of the resources used to run the object.
I would have to not only 2nd this, but also expand on it a bit.· I was looking at some objects for accelerometers.· One had a demo using TV output, the other VGA.· I had to scramble for a TV, and actually ended up using a camcorder, and then had to crawl down and unplug a monitor, etc.
While the ability to have TV and VGA output is great, I suspect that many users are not really that interested in it, and don't have ready connections (I'm sure many do).
Also, some of the demos seem more of a demo for the prop and graphics than for the device the object is written for.
My toughts on "ideal" demos:
PST based (if you can program the chip, you can connect the PST)
Interactive menu selection via PST
Where applicable, choices for one time shot vs "continuous" feedback (i.e. for sensors)
While not necessary, and possibly ineffecient code, have the demo set a variable to the return from the object, so that the user can easily see how to pull the value. (i.e. don't burry the call to the object inside the "PST.Dec() call:
myVar = obj.ObjCall()
PST.Dec(myVar)
Not
PST.Dec(obj.ObjCall())
Have a menu option for most/all functions of the object
Have a "query all" function that displays all outputs
Is the above practicable?· Possibly/Probably not, but it would make at least one version of an "ideal" demo for anyone (nOOb on up) to more easily understand how an object could/should be used.
I agree with John R. as do many of us internally - a simple demo should use PST for output. Anybody programming a Propeller already has PST and it minimizes the possibility of other problems being introduced to the demo. I'm sure that graphics and colors could provide a more useful display for most demos, but every demo must have at least a PST example.
Don't forget about PropTerminal. (written by Ariba) It provides a lot of VGA/NTSC functionality using only a connection
from the Propeller to a computer or laptop. Perhaps we need to highlight this tool a little more?
Ironically, we just talked about integrating PST into the Propeller Tool a couple hours ago, before we saw this thread.
We decided that the way we'd prefer to do it is to make it a feature that is changeable by the user; it would allow a user to configure the tool to launch an external exe if the Propeller Application that was just compiled included a specific object. This way, other "interfaces" to the Propeller could potentially be launched as the result of a Propeller download that included a certain, unique object.
The next release will, at least, include a menu item to launch PST from the Propeller Tool.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔ --Jeff Martin
· Sr. Software Engineer ·Parallax, Inc.
Post Edited (Jeff Martin (Parallax)) : 7/14/2010 6:16:57 PM GMT
Jen J. (Parallax Inc.) said...
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
Ok, so most people have moved on by now, but I wanted to actually think about this before replying.
In a "past life" I worked as a TA for an introductory programming class and I got to see (and work with) all levels of programmers (and potential programmers). I personally have been programming in one way or another for the vast majority of my life. I do a fair amount of re-implementation due to unmaintainability of the original. This is the perspective I bring to this OBEX guidelines question.
If the object does something complex, provide a thorough or at the very least indisputably clear discussion of how the object works (somewhere) in addition to a concise one in the code header. This should be in addition to the standard bootstrapping that we all like to see (aka "quick-start"). Ideally this complements code comments without making them obsolete. I consider information about I/O connections to be part of this--including a simple schematic if necessary.
Code should be decently commented. I'm not demanding line-by-line play-by-play for everything, but saying "Now we actually compute the checksum as discussed above" instead of no comment at all or "do some math" (provided you actually put some sort of explanation in the header) can make a big difference.
Brain-dump code is not OBEX code. I would not dare submit my work-in-progress code for an AX.25 KISS TNC to the OBEX in the state it is currently in (This thread on 6/29/2010 @ 23:08 UTC). Information about the path taken from Brain-dump to OBEX may turn out to be useful, but it belongs in attached documentation such as a README file.
Make it easy to tell if something implemented using the object demo is achieving minimum functionality. If that means outputting using a serial object (to the PST or otherwise) then give that a shot. Sometimes that doesn't make much sense, so in those cases some other relatively simple feedback mechanism should be available (e.g. potentiometer in --> airplane servo out; blink an LED; make a sound).
If a demo companion program is provided to be run on the PC, document the connection between the PC program and object at minimum. Referring to other documentation for details is ok. If it is written using something like Perl/TK please provide a version of it without a Win32/Win64 wrapper. This makes it easier for those of us whom don't normally use a Windows-based platform to get along with everyone else--and provides the community a chance to help make improvements.
Pointers about debugging something built with an object are always appreciated. Chances are that more than a few methods of debugging were used in the course of designing the object and some of those may prove to be useful in implementing it as well.
Objects should not be considered set-in-stone. Making it a reasonable proposition for others to make your code better (or better suited to their needs) is a virtue.
Assign credit where credit is due. My work on an AX.25 physical interface layer would not be at the level it is today without the work of Phil Pilgrim (PhiPi) preceding my own. Another individual wrote the CRC that I'm using. They deserve credit.
IN ADDITION if English isn't your first language, or you just want some help tweaking the documentation, you can request help. I suspect that there are a lot of people here in the forums who would be willing to assist in making a better object. Most people here seem at least reasonably capable of working in English, so I suspect that little complaint will arise from asking that English documentation be available even if it isn't the default.
Comments
Anyhow, I think an icon approach that links to the published "makes everyone happy" standard should be looked at. Also, you could use a "qualification class" system within that. In other words:
Class 1 Object = Meets all desired requirements (comments, docs, full demo, etc)
Class 2 Object = Meets minimum requirements and has a complete demo.
Class 3 Object = Meets Parallax minimum requirements for objects.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Andrew Williams
WBA Consulting
WBA-TH1M Sensirion SHT11 Module
Special Olympics Polar Bear Plunge, Mar 20, 2010
Most objects have not been made for obex but for a specific project of the autor. So the informations/hints must be present at the very early stage of the development of the object. So it would be great, if the PropTool and BST would provide·a template with all the hints which arealready have been mentioned above. For example in the CONstant section the names could be written in capitals automaticly. Or there could be a comment headline in the template: limits of the object. Some help to draw circuits would be nice. It is possible with the character set but it is not done very easily.
I wonder, if it was possible to bring an object into template format after it has been written, because I often do a lot of copying from different sources or I start from an existing example.
Of course once a year there is the big prize for the top object that was entered......
Christof
bst can do templates. Check out IDE Preferences->IDE Preferences->New File Template Directory.
Drop your spin files in there and they get added as templates in the Ctrl+N New menu.
If someone comes up with an absolute be-all end-all stonking great template I can easily include it compressed and compiled into bst like the PropBasic template is.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
"Are you suggesting coconuts migrate?"
While the ability to have TV and VGA output is great, I suspect that many users are not really that interested in it, and don't have ready connections (I'm sure many do).
Also, some of the demos seem more of a demo for the prop and graphics than for the device the object is written for.
My toughts on "ideal" demos:
Is the above practicable?· Possibly/Probably not, but it would make at least one version of an "ideal" demo for anyone (nOOb on up) to more easily understand how an object could/should be used.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
John R.
Click here to see my Nomad Build Log
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Ken Gracey
Parallax Inc.
Follow me at http://twitter.com/ParallaxKen for some insider news.
It would be great to develop code, download it, then just tab over to the terminal to watch it run!
from the Propeller to a computer or laptop. Perhaps we need to highlight this tool a little more?
www.insonix.ch/propeller/objects/PropTerminal_0.4.zip
I used it in my introduction to the Propeller a couple years ago..
www.parallax.com/Portals/0/Downloads/docs/prod/prop/32212-32812-Protoboard_Introduction.pdf
OBC
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
Propeller Feature Projects: PropellerPowered.com
Visit the: PROPELLERPOWERED SIG forum kindly hosted by Savage Circuits.
We decided that the way we'd prefer to do it is to make it a feature that is changeable by the user; it would allow a user to configure the tool to launch an external exe if the Propeller Application that was just compiled included a specific object. This way, other "interfaces" to the Propeller could potentially be launched as the result of a Propeller download that included a certain, unique object.
The next release will, at least, include a menu item to launch PST from the Propeller Tool.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
--Jeff Martin
· Sr. Software Engineer
· Parallax, Inc.
Post Edited (Jeff Martin (Parallax)) : 7/14/2010 6:16:57 PM GMT
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
John R.
Click here to see my Nomad Build Log
Ok, so most people have moved on by now, but I wanted to actually think about this before replying.
In a "past life" I worked as a TA for an introductory programming class and I got to see (and work with) all levels of programmers (and potential programmers). I personally have been programming in one way or another for the vast majority of my life. I do a fair amount of re-implementation due to unmaintainability of the original. This is the perspective I bring to this OBEX guidelines question.
IN ADDITION if English isn't your first language, or you just want some help tweaking the documentation, you can request help. I suspect that there are a lot of people here in the forums who would be willing to assist in making a better object. Most people here seem at least reasonably capable of working in English, so I suspect that little complaint will arise from asking that English documentation be available even if it isn't the default.
I hope that this is helpful.
▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔▔
--RvnPhnx