Turing Style Guideline
From Compsci.ca Wiki
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:
const FILE_PATH = "hello/world"
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.
this_is_ok thisToo
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.
var sInput : string
As is:
var strInput : string
Much better form would be something like:
var usersName : string
Or:
var inputName : string
Functions which return boolean values should indicate that in some way. Consider a function which tests if a string is empty.
Bad:
function empty (s : string) : boolean result s = "" end empty
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:
function is_empty (s : string) : boolean result s = "" end empty
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.
ThisIsGood AsIsThis But_this_is_bad andThisToo
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:
var name : string % name to be input by user
Good:
var nameInputByUser : string
When comments are employed, they should take a very specific format.
Comments should always precede the code to which they apply.
Bad:
something () % blah, blah
Good:
% blah, blah something ()
Comments should always be indented to match the indentation of the code they pertain to.
Bad:
% blah, blah something () % yada, yada something_else ()
Good:
% blah, blah something () % yada, yada something_else ()
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:
% blah, blah something () something_else ()
Good:
% blah, blah something () something_else ()
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:
%foo
Good:
% foo
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:
if someVariable = someOtherVariable then
foo
loop
baz
end loop
else
bar
end if
Good:
if someVariable = someOtherVariable then
foo
loop
baz
end loop
else
bar
end if
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:
foo if bar then baz end if loop qux end loop wooble ninja
Good:
foo if bar then baz end if loop qux end loop wooble ninja
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:
var x : int var y : string get x get y put y .. put x
Good:
var x : int var y : string get x get y put y .. put x
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:
var x : int if true then get x put x end if
Good:
if true then var x : int get x put x end if
Miscellaneous Whitespace Issues
In a variable declaration, whitespace should always separate commas, colons and initialization.
Bad:
var x,y:int
var x:int:=0
Good:
var x, y : int
var x : int := 0
Operators should benefit from whitespace. Leaving whitespace out will not make your code magically faster.
Bad:
x-y+z*4
Good:
x - y + z * 4
Do not place whitespace directly inside parentheses.
Bad:
( x - y + z ) * 4
Good:
(x - y + z) * 4
Do use blank lines to separate functions, procedures, records and processes.
Bad:
type A :
record
b : string
end record
function foo : string
result "foo"
end foo
procedure bar
baz
end bar
Good:
type A :
record
b : string
end record
function foo : string
result "foo"
end foo
procedure bar
baz
end bar
The same rules that hold for variable declarations apply for function, procedure and process parameter lists.
Bad:
function foo (bar:string) : string
Good:
function foo (bar : string) : string
Similarly, the colon leading the return type in a function should be surrounded by whitespace.
Bad:
function foo (bar : string):string
Good:
function foo (bar : string) : string
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:
foo (42,27)
Good:
foo (42, 27)
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:
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)
Good:
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)
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.
var foo : int := 0 procedure bar foo += 1 end bar
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.
procedure bar foo += 1 end bar var foo : int := 0
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:
if foo = "bar" then result 42 elsif foo = "baz" then result 42 else result 27 end if
Good:
if foo = "bar" or foo = "baz" then result 42 else result 27 end if
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:
if foo = "bar" then bar := 42 end if if foo = "baz" then bar := 27 end if
Good:
if foo = "bar" then bar := 42 elsif foo = "baz" then bar := 27 end if
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:
function foo (bar : int) : int
if bar < 27 then
result 3
end if
result 2
end if
Good:
function foo (bar : int) : int
if bar < 27 then
result 3
else
result 2
end if
end if
Please note that this practice may be used within a loop, to implement short-circuiting behavior.
