How to Write and Post a Great Propeller Object

The following are simple recommendations (they are not requirements) for writing and posting Propeller objects. You are free to adopt all, a few, or none as you see fit; however, your object's effectiveness in this community environment may be measured by its level of adoption of these recommendations.

Good Practice Guidelines for Object Writing

• Comments: Include descriptive comments to teach others how and why the object works. A well-written object often includes more comments than code.


• Symbols: Create self-describing symbol names for constants, variables, and methods; don't make them unnecessarily short or long.
  Example:

    TimeStamp  instead of  t  or  time_of_event_occurrence



• Notational Conventions: This is a subjective topic of personal preference. Just be sure to use character case, spacing, and alignment techniques in a consistent way throughout your code.


• Object Conventions: For a building-block object, make its first method(s) init, and/or start and stop, if the object has a configuration requirement and/or a cog-launching nature.

Organizing the Object

1. Title: Begin the object with its title, version, author, copyright and terms of use reference.


2. Brief Description: Following the title, include a brief description of the object's purpose, any hardware it requires, and how many cogs it will use.


3. Circuit Diagram: If the object interfaces with hardware, include at least a minimum circuit diagram.


4. Detailed Description: A detailed description should be placed after the circuit diagram, or near the end of object code. Note any limitations of the object clearly.


5. Configuration: Use CON block symbols for vital and user-configurable items and locate them near the top of the object. Include line-by-line comments to describe the symbols' purpose.


6. Code: Organize and group code blocks in the general order: CON, VAR, OBJ, PUB, PRI, and DAT.




1. PUB/PRI Method Descriptions: Each object method, especially those that are of public scope, should include a brief description of its purpose and its parameters.


2. Line-by-Line Comments: Use line-by-line comments for complicated or elusive code.




7. Theory of Operation: If the detailed description is expansive (including theory of operation, tables, examples, etc.), it may be best located near the end of the object.


8. License: The Terms of Use details (MIT License) should be included at the end of the object.

The Submission to OBEX

• Most submissions are for a building-block object; for this, include one or two demo objects that illustrate its use. One demo can be "bare bones" simple, the other elaborate and task-oriented, but both should be heavily commented.


• If your object requires other objects or data files, always archive it (Propeller Tool: File -> Archive…) even if some of the objects are not written by you.


• Provide a good description of the submission and carefully choose one or more appropriate categories.


• Upload a representative image, example audio or video files, and anything else that will help "sell" your object to the potential user browsing it.