Code Layout and Comments

Indentation

Indentation enhances readability, particularly within loops and conditional statements. Under PBL, standard practice is to indent four spaces per level.

	for i in 1..10 do
	    a[i] = 0
	end

To facilitate this, the Tab key inserts four spaces within the code editor.

The if-then-else class of statements should have the following form:

	if condition then
	    // statements
	end

or:

	if condition then
	    statements
	else
	    statements
	end

or:

	if condition then
	    statements
	elseif condition then
	    statements;
	else 
	    statements;
	end

Not:

	if condition
	then
	    statements
	end

And not:

	if condition then statements end

The chosen approach is considered to be better since each part of the if-else statement is written on separate lines of the file. This should make it easier to manipulate the statement, for instance, when moving else clauses around.

A bounded loop should have the following form:

	for i in set do
	    //statements
	end

An unbounded loop should have the following form:

	while condition do
	    //statements
	end

A Multipath conditional statement should have the following form:

	case condition
	when ABC 
	    // statements
	when DEF 
	    // statements
	else
	    // statements
	end

A Compound statement should have the following form:

	do
	    statements;
	on e as Exception exception
	    statements
	end

or:

	do
	    statements;
	on e as Exception 
	    statements
	on exit
	    statements
	end

White Space in Expressions

Conventional operators should be surrounded by a space character.
Reserved words should be followed by a white space.
Commas should be followed by a white space.
Colons should be followed by a white space.
Semicolons for statements should be followed by a space character.

	a = (b + c) * d

These rules make the individual components of the statements stand out and enhance readability. It is difficult to give a complete list of the suggested use of white space in Studio code. However, the examples shown above should give a general idea.

Note: Logical units within a compound statement should be separated by one blank line. This enhances readability by introducing a white space between logical units of a block.

Comments

Remember: Tricky code should not be commented on but rewritten.

In general, the use of comments should be minimized by making the code self-documenting through appropriate name choices and an explicit logical structure.

Tip: All comments should be written in English.

In an international environment, English is the preferred language.

Tip: Minimize the use of multi-line comments.

	// Comment spanning
	// more than one line

Since nested multi-line comments are not supported, using single line comments ensures that it is always possible to comment out entire sections of code for debugging purposes, among others.

Remember: Comments should be indented in relation to their position in the code.

	while true do
	    // Do something
	    something()
	end

Not:

	while true do
	// Do something
	    something()
	end

This is to prevent comments from breaking the logical structure of the program.

Files

Tip: File content must be kept within 100 columns.

Tip: The incompleteness of split lines should be made obvious.

	totalSum = a + b + c +
	                 d + e
	
	function (param1, param2,
	             param3)
	
	passingText ("Long line split" +
	             "into two parts.")

Split lines are required when a statement becomes too wide to read comfortably, or exceeds the column limit given above. It is difficult to provide strict rules for how lines should be split, but the examples above can serve to illustrate the guidelines shown below.

In general it is good practice to:

Break after a comma.
Break after an operator.
Align the new line with the beginning of the expression on the previous line.