Mod Development Best Practices

Mod development best practices, style guide, and refactoring tips

Variables

Name output variables

Using the generic default name of @output, @output2, etc. makes it hard to understand what the variable holds where it's used.

Remove unused brick output variables

If the output of a brick is not used in the mod component, remove the output variable. That makes the brick outline easier to read

See related rule Eliminate dead code

Avoid shadowing variable names

The Page Editor will warn you if you use a reserved variable name, e.g., @input or @options

Avoid using the same output variable name for two bricks in the same scope in the mod. Reusing variable names makes it more difficult to understand where the value came from.

It's OK to reuse names on different branches, e.g., the branches of an If-Elseor Try-Exceptbrick because the bricks are not in the same scope.

Control Flow

Eliminate dead code

Eliminate dead code (unused code) to make easier to read what will happen during mod execution:

• Unused output variables

• Conditions that always evaluate to false

• Commented out code in the Javascript brick

Panel Layout

Avoid negative margin

Applying negative margin is a code smell that indicates the a container's padding is incorrect. Negative margin might improve alignment, but is often insufficient to make elements perfectly aligned

Instead of applying negative margin, use stylesheets to control the base theme's spacing:

• Custom Themes/CSS

• Remove padding from embedded form fields

Mod Variables / State Management

Don't unnecessarily store values in mod variables

Encapsulation makes it easier to reason about code. When you introduce a mod variable, the reader must consider how other mod components might use/modify the value.

Don't store derived state in mod variables

Values that can be derived from one or more mod variables should be computed in a mod component instead of storing the derived value as a mod variable.

Storing the derived value complicates the mod state, and is error-prone for ensuring the mod variable invariants hold.

For example, suppose you have variables @mod.x , @mod.y , @mod.z. If logic needs to know if their sum is greater than 100, calculate the sum locally instead of creating a mod variable @mod.isSumGreaterThan100 . Otherwise, every location that updates any of the 3 variables must also update the derived value.

Refactor multiple boolean flag mod variables into a single variable encoding state

Tracking multiple boolean flags, e.g., isRecording and isSummarizing is error-prone because the invariants between the variables must be maintained at each update.

Instead, introduce a single string mod variable to track the state. The principle is to "Make Invalid States Unrepresentable". For example: introduce a variable state with values: recording, summarizing, done .

Store mod variable values in a local variable to perform calculations involving multiple bricks

Bricks in PixieBrix run asynchronously. Therefore, the value of @mod.x and @mod.y can change between brick calls if another mod component run updates the variable.

If a mod component need a consistent view of multiple values at a point in time, use the Identity Brick to store the values in a local variable.

JavaScript

When possible, use a single JavaScript brick to perform multiple functions instead of separating across multiple JavaScript bricks. You can use code comments inline to clarify which each function in the brick does.