BitRock Style: Miscellaneous Notes on Coding Style for BitRock InstallBuilder

Although BitRock InstallBuilder has a GUI, it is also practical to edit the sources, which are XML files, in an editor.

Beware that when you save the sources from the GUI, hand-edited files may be reorganised. For example, in many cases element siblings are rearranged into a sorted order. (Also beware that hand-edited files are not automatically re-loaded by the GUI; you must do this explicitly.)

Here I make some suggestions for trying to keep BitRock sources readable.

Comments

In most places, comments will be preserved.

Use XML-style comments to help explain sections of the installer. These may even be viewed in the GUI when you “edit the XML code”.

<!-- use comments to provide additional information or explanation -->

Blocks

There are places where a group can be used. Often this marks a semantic boundary, is associated with control flow, or allows a compound construct in a context where a simple construct is expected.

However, a block could also be used to help delimit the scope of a comment.

For example:

<actionList>
  <!-- Write the configuration files -->
  <writeFile ... />
  <writeFile ... />
  <writeFile ... />
  <!-- Write the sample files -->
  <writeFile ... />
  <writeFile ... />
  <writeFile ... />
</actionList>

might be more clearly re-written

<postInstallationActionList>
  <actionGroup>
    <!-- Write the configuration files -->
    <actionList>
      <writeFile ... />
      <writeFile ... />
      <writeFile ... />
    </actionList>
  </actionGroup>
  <actionGroup>
    <!-- Write the sample files -->
    <actionList>
      <writeFile ... />
      <writeFile ... />
      <writeFile ... />
    </actionList>
  </actionGroup>
</postInstallationActionList>

although this is obviously more verbose. Such grouping is reflected in the GUI, which could make the tree-view of the project more manageable.

Even without comments, it may be clearer to group related items (parameters, actions,…) in this way.

Child or Attribute?

In BitRock elements, properties may often be expressed either as a child or as an attribute.

For example

<setInstallerVariable name="versionMajor">
  <value>1</value>
</setInstallerVariable>

is equivalent to

<setInstallerVariable>
  <name>versionMajor</name>
  <value>1</value>
</setInstallerVariable>

I tend to use the former to declare, define or initialise an important symbol (parameter, variable, function,…), and the latter for ordinary assignments and for temporary, local or minor symbols. This tends to be useful when searching the sources.

Compound Rules

The evaluation logic for a rule list may be expressed in a sibling as, e.g.

<ruleEvaluationLogic>or</ruleEvaluationLogic>
<ruleList>
  <compareText logic="equals" text="" value="${verMajor}"/>
  <compareText logic="equals" text="" value="${verMinor}"/>
  <compareText logic="equals" text="" value="${verPatch}"/>
</ruleList>

but this may also be expressed on an attribute of a rule group

<ruleList>
  <ruleGroup ruleEvaluationLogic="or">
    <ruleList>
      <compareText logic="equals" text="" value="${verMajor}"/>
      <compareText logic="equals" text="" value="${verMinor}"/>
      <compareText logic="equals" text="" value="${verPatch}"/>
    </ruleList>
  </ruleGroup>
</ruleList>

I tend to use the latter, even though it’s a little more verbose, as siblings tend to get separated (sometimes even if the tag names are alphabetically close). The latter will always keep the related logic together.

Function Names

It is possible to define common actions in functions. I tend to name my functions with ‘function’ as a prefix, and to place my functions in a file named closely to the function’s name.

This helps distinguish user-defined functions from any built-in functionality.

Advertisements

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s


%d bloggers like this: