Protected Regions

The key feature that allows for human developers to work along side bots is the existence of protected regions. A protected region is a way of taking the ownership of snippets of code away from the bot so they can be customised or further snippets can be added. However, please note that you are not able to create new protected regions yourself. If there is not a protected region in a location that you require, there is a specific process for requesting new protected regions be added to your project (this is detailed in the next slide).

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 similar to how the Bot Written Warning works.

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.

An ID of a protected region may also be called its “label” or “name”.

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 doubles as a description or suggestion of what can go into the protected region. This ID must be unique for any given file it appears in, and you are not able to modify the ID names. 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:

• off begin
• 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 a protected region can be in:

• active
• 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 treated as the special bounded space it is, and is not touched 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 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 it has written vs. those which 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.