[WIP] Draft of Style Guidelines

[wtd]

Turing Style Guidelines

Naming Conventions

Constants

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

code:

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.

code:

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.

code:

var sInput : string

As is:

code:

var strInput : string

Much better form would be something like:

code:

var usersName : string

Or:

code:

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:

code:

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:

code:

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.

code:

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:

code:

var name : string % name to be input by user

Good:

code:

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:

code:

something () % blah, blah

Good:

code:

% blah, blah something ()

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

Bad:

code:

% blah, blah    something ()        % yada, yada  something_else ()

Good:

code:

% 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:

code:

% blah, blah something () something_else ()

Good:

code:

% 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:

code:

%foo

Good:

code:

% 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:

code:

if someVariable = someOtherVariable then  foo  loop  baz  end loop else     bar end if

Good:

code:

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:

code:

foo if bar then    baz end if loop    qux end loop wooble ninja

Good:

code:

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:

code:

var x : int var y : string get x get y put y .. put x

Good:

code:

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:

code:

var x : int if true then    get x    put x end if

Good:

code:

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:

code:

var x,y:int

code:

var x:int:=0

Good:

code:

var x, y : int

code:

var x : int := 0

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

Bad:

code:

x-y+z*4

Good:

code:

x - y + z * 4

Do not place whitespace directly inside parentheses.

Bad:

code:

( x - y + z ) * 4

Good:

code:

(x - y + z) * 4

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

Bad:

code:

type A :    record       b : string    end record function foo : string    result "foo" end foo procedure bar    baz end bar

Good:

code:

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:

code:

function foo (bar:string) : string

Good:

code:

function foo (bar : string) : string

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

Bad:

code:

function foo (bar : string):string

Good:

code:

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:

code:

foo (42,27)

Good:

code:

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:

code:

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:

code:

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.

code:

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.

code:

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:

code:

if foo = "bar" then    result 42 elsif foo = "baz" then    result 42 else    result 27 end if

Good:

code:

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:

code:

if foo = "bar" then    bar := 42 end if if foo = "baz" then    bar := 27 end if

Good:

code:

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:

code:

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

Good:

code:

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.

[Clayton]

Good stuff wtd, far too many a time have I looked at code and shied away simply because it was so hard to read due to unconventional conventions. Perhaps this should be included in the Turing Walkthrough?

[Cervantes]

Freakman wrote:

Perhaps this should be included in the Turing Walkthrough?

Excellent idea. It's been done:

Walkthrough wrote:

This walkthrough is like a book, except it's pieced together from articles written by different people. As a result, writing and teaching styles will change; what's more, naming conventions may change from one article to the next. This is regrettable. The best thing you can do is to follow the conventions, yourself, even if you are from time to time reading some code that doesn't follow these conventions. So, while working through this walkthrough, keep the Style Guidelines handy and refer to it often.

Terrific job, wtd. This was much needed.

[uberwalla]

im sorry if it was just said lol but i read this 5 min ago and randomly had a question. why is it so bad to have the first letter of a proc capital or w.e?

[wtd]

Consistent naming conventions make code more readable. But consistency alone doesn't aid in that. Using naming to differentiate names in a program is important.

[uberwalla]

ok i get it
it was a little weird at first of why it mattered but now i see

thx

[ericfourfour]

I see where you are coming from uberwalla. My teacher (most likely ignorant of naming conventions) tells us to write our methods with capitals. However, this is the same teacher who recommended making every variable public and assigning their values in the main method. The way you are taught it is not always the correct way. It may however, be the easier way to teach it. This is one thing you have to look out for.

[wtd]

As these guidelines are updated, I strongly encourage others to provide constructive feedback. I will not feel comfortable removing the "Draft" bit until I get that feedback, and approval of the contents.

[Clayton]

So far so good wtd, the only thing I have to say is:

wtd wrote:

code:

type A : record     b : string end record

is not proper turing style, it should instead be:

code:

type A :     record         b : string     end record

other than that, no complaints

[wtd]

Good point. My goal is at least partly to create guidelines that don't force students to fight the editor's built-in formatting style.

[[Gandalf]]

Well, if you insist...

wtd wrote:

Comments should always precede the code to which they apply.

Bad:

code:

something () % blah, blah

Good:

code:

% blah, blah something ()

This is something I firmly disagree with. No reason in particular, but keeping things in as few lines as possible while still being neat is something I try to follow. It also makes it easier to associate the comment with the code, at least for me. Any particular reason you included this? Is it all that important?

Otherwise, seems quite agreeable.

[wtd]

Comments should explain only things which the code does not make apparent to those who know the language. Things like details of algorithms, especially those associated with specialty fields.

Good comments might also explain why a programmer felt a certain variable or function was important.

As such, I believe it important that the reader go into reading the actual code with some understanding of what the purpose of it is.

[ericfourfour]

Personally, I prefer the way wtd presented the comments but either the line before or the line of the code is acceptable.

Maybe the "/**/" comment can be added into the tutorial.

[wtd]

A question, if I may.

Should naming conventions be simplified for variables, functions and the like? Upon further consideration, Turing style leads one to already include a lot of whitespace, and I fear that underscores might get lost in all of that. As a result, despite a personal preference for that type of name, I am beginning to suspect that camel-case might be the appropriate single guideline for naming such things.

[zylum]

i always use camel case for variable names. i only use underscores for constants where the letters are allcaps and i dont really have any other choice. for me its just as easy to read and i find it more aesthetically pleasing than using underscores.