How to Write and Post a Great Propeller Object

The few 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. Clearly note any limitations of the object.
  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.
    • 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.
    • 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.

nike free run 5.0 nz