Turing Style Guideline

From Compsci.ca Wiki

Revision as of 14:36, 11 October 2008 by Cavetroll (Talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Contents

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.

Retrieved from "http://wiki.compsci.ca/index.php?title=Turing_Style_Guideline"
Personal tools