How to write a Propeller Object (document) - Am I missing anything?

Microcontrolled

I have written a short 2 page document on how to write an submit a Propeller object. It works in way up in an 8 step instruction-style guide. I was wondering if I was missing anything or had included anything unnecessary, constructive criticism is welcome.

I'm hoping that this can be a useful guide to first-time object writers, it includes several helpful tips.

Thanks,
Micro

ElectricAye

Microcontrolled wrote: »

...I was wondering if I was missing anything....

Micro,

Looks good to me, except I would include a step that has the writer post the code on the forum for testing by forum members before publication on the OBEX itself. Nobody wants a zombie object sitting in the OBEX awaiting band-aids.

Also, you might want to boldface things like "repeat...from" and waitcnt, etc. so people know they are code.

It probably wouldn't hurt to have little boxes of snippet SPIN code that explain what you mean about showing pinouts, etc. Anybody with enough experience to write objects will probably know what you mean, but, as they say, a picture is worth a thousand words.

Check out the differences between the words "then" and "than". It's a common mistake, intelligent people make it all the time, but once in a great while the "trivial" difference does make a difference.

cheers,

TinkersALot

How about topics such as:

Code For Re-Use
No Magic Numbers -- prefer constant definitions
Define all "pin references" to constants
Include schematics in the program files?

jazzed

>> Some people name the function you call first “Init” or “Initialize”, but “Start” is basic and easy to remember if you are using multiple objects.

Start is used with Stop. Start starts a cog. Init usually does not start a COG. I tend to use "pub main" as the very first method run by the interpreter - old habits die hard.

>> Also, the standard variable name for the incrementing variable in a repeat...from loop is “i”, and since repeat...from loops may be used in many different routines, “i” should be declared as a local variable and not a global variable.

Letter "i" is a horrible variable name even for a small repeat loop. Count the number of "i" in this message. If you must suggest a single letter variable, it should be a consonant like j,k,m,n. Never use l Yes, such little variables should be local.

Long variable names make reading code just as hard as short cryptic variable names. It's best to find a good middle ground. Using extremes is amateurish. AvoidSentenceMethodOrVariableNames !

>> Comment your code. You should have a comment section at the top of every PUB routine explaining how to implement the object into code.

Describe all input parameters and return value usage. Never use 51 variables for parameters


May I suggest that schematics using non-ascii symbols be put in a separate file? The schematic file can be included like other files with the obj section for the purpose of making a .zip archive. Using only ascii text allows files to be saved as text mode only which is more broadly accepted by programmers.

LukeH

Perhaps consider including a one-page snippet of example code which illustrates all the coding practices you describe. You can then place footnotes in your text which point to various parts of the example code. I think this would be a great visual aid and provide a starting point from which a new-object writer could follow along as he reads your guide.

Additionally, when uploading the file to the OBEX, be sure to include the object's title in the description field, as this will help the search functionality.

Microcontrolled

@Electric Eye: Sure! I've been known for the notorious "then/than" mixup, so I'll look through and correct that. :-)
@TinkersALot: Sounds good. I'll be sure to include that, I knew I would forget something in the object writting suggestions.