[WIP] Draft of Style Guidelines

[Clayton]

I, on the other hand, find using this_kind_of name easier to read as it leaves some space in between seperate words (thereby making it easier to read), but, to each his own I suppose.

[md]

I use underscores for variables, and it makes things a lot easier to read. I use CamelCase for functions though, in part because they then stand out from variables, and in part because of habit.

[TokenHerbz]

i use the underscores only in parameter variables...

as for comments, i do it on the same line as the code, with the expetion of a few things which i have to fully type out... like crazy collition crap.

code:

proc setUnitHealth (unitHealth_: string)  %% A comment like this for here     unitHealth := unitHealth_ end setUnitHeath

preferences i suppose.

[Clayton]

I find that if you need a comment that will still fit on the line of code that it is used for, you don't need it, becuase the code should be fairly well explained that it doesn't need that short of a comment. This of course is different when it comes to crazy algorithms and such, but then you just comment on the line above.

@TokenHerbz : thats "collision", you keep spelling it wrong.

[Cervantes]

TokenHerbz wrote:

i use the underscores only in parameter variables...

I think this is a bad distinction to make. Parameters are so much like regular variables that I think they should have the same naming convention.

Also, your style uses both CamelCase and underscores. What's the purpose of the underscore at the end of the parameter name? Is it just to stand out and say, "I am a parameter"? Ideally, you should only be using parameters in your subroutines, so there should be no need for your parameters to stand out, since they would all stand out equally.

[Clayton]

I think he means whenever he is using a class or something and he has values that he wants to have the "same" name so he adds the underscore to the end of the name to distinguish the parameters and the class variables ie:

Turing:

class Foo     export bar     var baz, floo : int         procedure bar (baz_, floo_ : int)         baz := baz_         floo := floo_     end bar end Foo

see?

NOTE: I have seen you do this very thing in your classes tutorials Cervantes, just to show you what I mean.

[Cervantes]

Ah! Yeah, I could dig that.

[wtd]

How about "newBazValue" or "initialBazValue"?

[Clayton]

Yes, I suppose that could work too, but the underscore after parameters in classes, and only classes, is pretty much automatic for me, and possibly others as well. For me it keeps things organized, and I can easily tell what is what at first glance. Although, I also see what you mean wtd. I suppose either way works, just keep it constant.

[[Gandalf]]

This is why I like the 'this' keyword, it makes the distinction between two variables with the same name much more obvious.

About the commenting, I see what you mean wtd, but I wouldn't go so far as saying this is always the case. Comments aren't always used to explain the code in question, they can also contain things like previously tested arguments, no?

[wtd]

You're talking about commenting out test code?

[Clayton]

Actually I think he is talking more about commenting about stuff that was tried, but failed, or is a work in progress (correct me if I'm wrong).

[wtd]

I see nothing wrong with that, but it should be accompanied by a well-formed comment indicating that.

[iamcow]

I would like to add to the style guidelines:

Rand.Int is preferred over randint

A function that returns a value is preferred over a procedure that changes the parameters that it is given.

And from a very practical point of view:

scenario: drawing random circles

code:

loop var x,y,xrad,yrad, cred,cgreen,cblue:=0 randint (x,0,maxx) randint (y,0,maxy) randint (xrad,1,200) randint (yrad,1,200) randint (cred,1,1000) randint (cgreen,1,1000) randint (cblue,1,1000) drawfilloval (x,y,xrad,yrad,RGB.AddColor (cred/1000,cgreen/1000,cblue/1000)) end loop

Now with Rand.Int:

code:

loop     drawfilloval (Rand.Int (0, maxx), Rand.Int (0, maxy), Rand.Int (5, 200), Rand.Int (5, 200), RGB.AddColor (Rand.Real, Rand.Real, Rand.Real)) end loop

we've both decreased the lines and the number of global variables

Also, efficiency runtime - wise

code:

for i : 1 .. 500     var x, y, xrad, yrad, cred, cgreen, cblue := 0     randint (x, 0, maxx)     randint (y, 0, maxy)     randint (xrad, 1, 200)     randint (yrad, 1, 200)     randint (cred, 1, 1000)     randint (cgreen, 1, 1000)     randint (cblue, 1, 1000)     drawfilloval (x, y, xrad, yrad, RGB.AddColor (cred / 1000, cgreen / 1000, cblue / 1000)) end for put Time.Elapsed

code:

for i: 1..500     drawfilloval (Rand.Int (0, maxx), Rand.Int (0, maxy), Rand.Int (5, 200), Rand.Int (5, 200), RGB.AddColor (Rand.Real, Rand.Real, Rand.Real)) end for put Time.Elapsed

After running both one concludes also that Rand.Int is faster. Perhaps not directly, but in the structure of the program when Rand.Int is used

[ericfourfour]

iamcow that is a common thing seen in many early Turing programs. Maybe wtd could add in a section about the downside of procedures that use var parameters.