×
Back to book

Protected Regions

An overview of what Protected Regions are, why we need them, and how to use them.

A protected region is a section in bot-written code that is considered sacred by the bot and as such is not touched when the bot re-writes the code. They are denoted by special comment tags. For example, the protected region comment in a Java file would appear as follows.

// % protected region % [Add any additional imports here] off begin

// % protected region % [Add any additional imports here] end

A protected region is a bounded space in a file. It must have a opening and closing comment tag, which are linked via the ID. Both comments have three parts: start, ID, and end.

Start

The start of a protected region will always contain the text protected region regardless of the language the region appears in. In the above example, the start is deliminated for readability. i.e % protected region %.

ID

As well as being an identifier, the ID of a protected region also doubles as a description or suggestion of what can go into the protected region. Again, this is an ID, so it must be unique for any given file that it appears in. Duplicate protected regions (as denoted by their ID) in the same file can cause undefined behaviour.

The ID of the previous example is Add any additional imports here and it is deliminated by the [] to increase readability.

End

The end of a protected region tag is the only one of the three that differs between the opening tag and the closing tag of a protected region.

The opening tag starts the bounded space. The end of a protected region can take two forms:

  1. off begin
  2. on begin

The meaning of these two states will be covered later (in "How to use a protected region").

Anything following the begin keyword is considered part of the protected region. i.e

// % protected region % [Add any additional imports here] off begin A
B
C 
// % protected region % [Add any additional imports here] end

In the above example, the content of the protected region is the following characters, SPACE, A, \n, B, \n, C, \n

How to use a protected region

There are two states that a protected region is in.

  1. active
  2. inactive

More simply put, a protected region is either on or off.

If it is off, it does nothing and can be treated like any other comment in the code, when on or active, a protected region is not treated as the special bounded space that it is by the bot. To turn a protected region on or off, simply change the text of the end of the opening tag that is denoted by the off keyword to on.

i.e.

// % protected region % [Add any additional imports here] off begin
// % protected region % [Add any additional imports here] end

/** TURN THE ABOVE protected region on **/

// % protected region % [Add any additional imports here] on begin
// % protected region % [Add any additional imports here] end

While off, the protected region can be updated by the bot as needed, for example, any code that the bot initially places within a protected region can be updated as the bot is updated.

For example, if the bot was updated to change the string from "John" to "John Smith",

// % protected region % [Add any additional imports here] off begin
var name = "John";
// % protected region % [Add any additional imports here] end

/** THE BOT IS UPDATED AND RUNS AGAIN **/

// % protected region % [Add any additional imports here] off begin
var name = "John Smith";
// % protected region % [Add any additional imports here] end

If this protected region was turned on, this update would not have been possible as the code within the two bounding comments would have been considered untouchable by the bot.

By default, all protected regions are created as inactive.

Different File Types

The protected region structure may differ slightly depending upon the file type to adapt for the different ways of commenting. For example, in a feature file, it would look like:

# % protected region % [Add additional steps for 'Display Create Page'] off begin
# % protected region % [Add additional steps for 'Display Create Page'] end

Statistics

When the bot runs, it reports on the number of lines of code that it has written vs. that have been written by a human. Any code that exists in a non-bot written file, or within an active protected region is considered human written.