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.
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
- 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.
- Circuit Diagram: If the object interfaces with hardware, include at least a minimum circuit diagram.
- 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.
- 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.
- 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.
- 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.
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.