Turing Style Guideline

2008-10-11T14:36:52Z

Cavetroll: /* Comments */

== Introduction ==

The following introduces a set of style guidelines to follow when writing [[Turing]] code. Doing so will promote readability of code and positive communication between programmers.

== Naming Conventions ==

=== Constants ===

Constants should be typed in all-caps, with underscores used to separate words. For instance:

<pre>const FILE_PATH = "hello/world"</pre>

Unless they have some obvious mathematical meaning, very short names should not be used.

=== Variables, functions and procedures ===

Variable, function and procedure names should begin with a lower-case letter. Subsequent words should be separated either using an underscore, or by capitalization.

<pre>this_is_ok
thisToo</pre>

Whichever style is chosen should be used consistently throughout a program. As with constants, short variable names should be eschewed in favor of expressive variable names.

Variable names should not be prefixed with any kind of indicator as to what type they are. For instance, if one is writing a program which asks the user for a name, the following is considered bad form.

<pre>var sInput : string</pre>

As is:

<pre>var strInput : string</pre>

Much better form would be something like:

<pre>var usersName : string</pre>

Or:

<pre>var inputName : string</pre>

Functions which return boolean values should indicate that in some way. Consider a function which tests if a string is empty.

Bad:

<pre>function empty (s : string) : boolean
result s = ""
end empty</pre>

The word "empty" in the English language can be used as a verb, yet we are not modifying the state of anything. Much more appropriate would be something like:

<pre>function is_empty (s : string) : boolean
result s = ""
end empty</pre>

You will note that the argument to the function "is_empty" had a one character name. Previously this was discouraged. However, it should be noted that functions are meant to act as "black boxes" about whose implementation we do not need information.

One of these pieces of information is the name of arguments. Normally this would not be sufficient argument for shortening the name. However, in this case the argument exists in a very small scope, and its purpose is not difficult to determine.

=== Types ===

The names of types should begin with a capital letter. All subsequent words should be capitalized.

<pre>ThisIsGood
AsIsThis
But_this_is_bad
andThisToo</pre>

== Comments ==

First and foremost, comments should not be used to specify facts about a program which can be determined by simply reading the code. Meaningful variable, function and procedure names should alleviate much of the need for comments.

Bad:

<pre>var name : string % name to be input by user</pre>

Good:

<pre>var nameInputByUser : string</pre>

When comments are employed, they should take a very specific format.

Comments should always precede the code to which they apply.

Bad:

<pre>something () % blah, blah</pre>

Good:

<pre>% blah, blah
something ()</pre>

Comments should always be indented to match the indentation of the code they pertain to.

Bad:

<pre>% blah, blah
something ()

% yada, yada
something_else ()</pre>

Good:

<pre> % blah, blah
something ()

% yada, yada
something_else ()</pre>

When commenting in this manner, it is best to separate the code to which the comment pertains from the rest of the code by a single blank line.

Bad:

<pre>% blah, blah
something ()
something_else ()</pre>

Good:

<pre>% blah, blah
something ()

something_else ()</pre>

Comments should be well-formed sentences. They should be capitalized correctly, and contain proper spelling and punctuation.

Comments should line-wrap as necessary to avoid the line they are on exceeding 80 columns wide.

Comments should contain a single space between the comment delineator and the beginning of the comment.

Bad:

<pre>%foo</pre>

Good:

<pre>% foo</pre>

== Indentation ==

The contents of functions, procedures, record declarations, classes, loops, conditions, case statements, etc. should all be indented.

Indentation may be three spaces, four spaces, one tab, etc. Whatever you choose to use, use it consistently.

Bad:

<pre>if someVariable = someOtherVariable then
foo
loop
baz
end loop
else
bar
end if</pre>

Good:

<pre>if someVariable = someOtherVariable then
foo

loop
baz
end loop
else
bar
end if</pre>

== Control Structures and Whitespace ==

It is immensely helpful to separate control structures (conditionals or loops) from surrounding code at the same levek of indentation with a single blank line.
Bad:

<pre>foo
if bar then
baz
end if
loop
qux
end loop
wooble
ninja</pre>

Good:

<pre>foo

if bar then
baz
end if

loop
qux
end loop

wooble
ninja</pre>

== Variable Declarations and Whitespace ==

Multiple variable declarations may appear on adjacent lines. However, they should be separated from surrounding code at the same indentation level by a blank line.

Bad:

<pre>var x : int
var y : string
get x
get y
put y ..
put x</pre>

Good:

<pre>var x : int
var y : string

get x
get y
put y ..
put x</pre>

== Scope ==

Variables should be scoped as minimally as possible. If a variable is only used within a conditional structure or loop, then it should be scoped to that structure.

Bad:

<pre>var x : int

if true then
get x
put x
end if</pre>

Good:

<pre>if true then
var x : int

get x
put x
end if</pre>

== Miscellaneous Whitespace Issues ==

In a variable declaration, whitespace should always separate commas, colons and initialization.

Bad:

<pre>var x,y:int</pre>

<pre>var x:int:=0</pre>

Good:

<pre>var x, y : int</pre>

<pre>var x : int := 0</pre>

Operators should benefit from whitespace. Leaving whitespace out will not make your code magically faster.

Bad:

<pre>x-y+z*4</pre>

Good:

<pre>x - y + z * 4</pre>

Do not place whitespace directly inside parentheses.

Bad:

<pre>( x - y + z ) * 4</pre>

Good:

<pre>(x - y + z) * 4</pre>

Do use blank lines to separate functions, procedures, records and processes.

Bad:

<pre>type A :
record
b : string
end record
function foo : string
result "foo"
end foo
procedure bar
baz
end bar</pre>

Good:

<pre>type A :
record
b : string
end record

function foo : string
result "foo"
end foo

procedure bar
baz
end bar</pre>

The same rules that hold for variable declarations apply for function, procedure and process parameter lists.

Bad:

<pre>function foo (bar:string) : string</pre>

Good:

<pre>function foo (bar : string) : string</pre>

Similarly, the colon leading the return type in a function should be surrounded by whitespace.

Bad:

<pre>function foo (bar : string):string</pre>

Good:

<pre>function foo (bar : string) : string</pre>

In a call of a function, procedure or process, arguments should be separated by whitespace. Again, leaving out the whitespace does nothing to make code better, and does make it harder to read.

Bad:

<pre>foo (42,27)</pre>

Good:

<pre>foo (42, 27)</pre>

== Code Organization ==

Turing, unlike many other statically, manifestly typed programming languages, does not have a designated entry point.

Code that can be executed is, in order, as it appears in the source code. This means such things can be interspersed with type, function, procedure and process definitions.

Despite the fact that this can be done, does not mean it should.

Bad:

<pre>var userInputString : string

function getString : string
var s : string

get s ..
result s
end getString

userInputString := getString

function reverseString (stringToReverse : string) : string
var outputString : string := ""

for decreasing characterIndex : length (stringToReverse) .. 1
outputString += stringToReverse (characterIndex)
end for

result outputString
end reverseString

put reverseString (userInputString)</pre>

Good:

<pre>function getString : string
var s : string

get s ..
result s
end getString

function reverseString (stringToReverse : string) : string
var outputString : string := ""

for decreasing characterIndex : length (stringToReverse) .. 1
outputString += stringToReverse (characterIndex)
end for

result outputString
end reverseString

var userInputString : string

userInputString := getString
put reverseString (userInputString)</pre>

Additionally, so that they are available to the rest of the code, type declarations should appear at the top of your code.

== Functions vs. Procedures: Two Enter. One Leaves. ==

Procedures are probably what every Turing programmer is first introduced to in terms of organizing executable code. As it happens, they are also one of the first things that should, for the most part, be left behind.

Procedures typically act on some set of global variables.

<pre>var foo : int := 0

procedure bar
foo += 1
end bar</pre>

You may note that this directly contradicts the style promoted in the Code Organization section. There was good reason for the style advocated there. A variable declared after a procedure is not visible to that procedure's inner workings.

The following would result in an error.

<pre>procedure bar
foo += 1
end bar

var foo : int := 0</pre>

The problem with procedures is that they explicitly refer to some set of variables outside their own scope. They are tied down to using just those variables. They are also dependent on those variables for their internal behavior.

A function's implementation, on the other hand, is separate from its external environment. It communicates with the outside world via the arguments passed into it, and the value it returns.

Whenever possible, seek a solution which uses functions rather than procedures.

== Conditionals and Redundancy ==

If, in the course of writing a conditional, you find that multiple branches have the exact same result, then you almost certainly should use "or".

Bad:

<pre>if foo = "bar" then
result 42
elsif foo = "baz" then
result 42
else
result 27
end if</pre>

Good:

<pre>if foo = "bar" or foo = "baz" then
result 42
else
result 27
end if</pre>

It is bad practice to use multiple conditionals when the results are exclusive. That is, if only one of them will actually run, you should use a single conditional with multiple branches.

Bad:

<pre>if foo = "bar" then
bar := 42
end if

if foo = "baz" then
bar := 27
end if</pre>

Good:

<pre>if foo = "bar" then
bar := 42
elsif foo = "baz" then
bar := 27
end if</pre>

== Conditionals and Control Flow ==

It is bad practice to use a conditional to break control flow and skip around the remainder of the function or procedure, if the same can be expressed as a conditional with multiple branches.

This practice technically works fine, but makes it more tedious to reason about the control flow, and yields no significant gain.

Bad:

<pre>function foo (bar : int) : int
if bar < 27 then
result 3
end if

result 2
end if</pre>

Good:

<pre>function foo (bar : int) : int
if bar < 27 then
result 3
else
result 2
end if
end if</pre>

Please note that this practice may be used within a loop, to implement short-circuiting behavior.

Compsci.ca Wiki - User contributions [en]

Turing Style Guideline