Programming C, C++, Java, PHP, Ruby, Turing, VB
Computer Science Canada 
Programming C, C++, Java, PHP, Ruby, Turing, VB  

Username:   Password: 
 RegisterRegister   
 [WIP] Draft of Style Guidelines
Index -> Programming, Turing -> Turing Tutorials
Goto page 1, 2, 3  Next
View previous topic Printable versionDownload TopicRate TopicSubscribe to this topicPrivate MessagesRefresh page View next topic
Author Message
wtd




PostPosted: Sun Nov 26, 2006 5:54 pm   Post subject: [WIP] Draft of Style Guidelines

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.
Sponsor
Sponsor
Sponsor
sponsor
Clayton




PostPosted: Thu Nov 30, 2006 10:10 pm   Post subject: (No subject)

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




PostPosted: Fri Dec 01, 2006 5:48 pm   Post subject: (No subject)

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. Smile
uberwalla




PostPosted: Fri Dec 01, 2006 6:45 pm   Post subject: (No subject)

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




PostPosted: Fri Dec 01, 2006 6:57 pm   Post subject: (No subject)

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




PostPosted: Fri Dec 01, 2006 7:13 pm   Post subject: (No subject)

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

thx
ericfourfour




PostPosted: Sat Dec 02, 2006 2:23 am   Post subject: (No subject)

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




PostPosted: Mon Dec 04, 2006 1:39 pm   Post subject: (No subject)

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




PostPosted: Mon Dec 04, 2006 3:49 pm   Post subject: (No subject)

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 Very Happy
wtd




PostPosted: Mon Dec 04, 2006 4:21 pm   Post subject: (No subject)

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]




PostPosted: Mon Dec 04, 2006 6:17 pm   Post subject: Re: [WIP] Draft of Style Guidelines

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. Smile
wtd




PostPosted: Mon Dec 04, 2006 7:31 pm   Post subject: (No subject)

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




PostPosted: Mon Dec 04, 2006 7:47 pm   Post subject: (No subject)

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




PostPosted: Thu Dec 07, 2006 2:16 am   Post subject: (No subject)

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




PostPosted: Thu Dec 07, 2006 2:58 am   Post subject: (No subject)

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.
Display posts from previous:   
   Index -> Programming, Turing -> Turing Tutorials
View previous topic Tell A FriendPrintable versionDownload TopicRate TopicSubscribe to this topicPrivate MessagesRefresh page View next topic

Page 1 of 3  [ 31 Posts ]
Goto page 1, 2, 3  Next
Jump to:   


Style:  
Search: