Coding Standards

From OHRRPGCE-Wiki
Jump to navigationJump to search

HamsterSpeak is a very syntactically flexible language. Whitespace is almost entirely ignored, many symbols have textual representation, and so forth. However, this flexibility can also be a bad thing if it results in messy, hard to follow code. On the Wiki, this is extra important, as many of the code examples are intended to assist beginners in learning.

Note: This article was intended for the OHR Wiki. However, you are free to adopt these standards in your own coding.

Posting Code[edit]

Before we jump into the code itself, a quick tutorial on how to actually post code:

<pre>
script, foo, begin

#blah

end
</pre>

--OR--

 script, foo, begin
 
   #blah
 
 end

(Note the leading spaces, even on the blank lines)

Please do not just post a script as plain text, as it can be difficult to read.

White Space[edit]

As mentioned above, the compiler will ignore whitespace just about anywhere, in a process known to computer scientists as "smushing". However, for the sake of our readers, do not take full advantage of this:

Wrong:

s cr i     p t, f               oo,beg   in,
  bla   h                                          (12,end)

Instead, all keywords should be written without embedded white space ("begin" instead of "be gin", etc.), and all function names should be written as they appear in the Plotscripting Dictionary (which is, generally, as it would be in english "key is pressed" instead of "keyispressed"). Also, please put only a single command on a line.

Also, there should be a single space after a comma, to keep lists and the like neat and tidy, and a space between a function and its parameters.

Right:

script, foo, begin
  blah (12)
end

Begin and End[edit]

In all but a few cases, one can freely interchange begin with (, and end with ). That doesn't mean you should, however.

Wrong:

script, foo,(
  blah, begin, 12)
  bar(42,end,end

Instead, the general guidelines are:

  • Use ( and ) for parameters
  • Use begin and end for blocks (if, script, etc.)

Right:

script, foo, begin
  blah (12)
  bar (42)
end

Variables[edit]

When naming and choosing variables, keep these things in mind:

  • They should be descriptive
  • They should be short
  • There should enough variables that you don't have to "reuse" them...
    • ... but no more.

Wrong:

script, foo, begin
  variable (a,b,c)
  a:= get hero picture (1)
  b:= 12
  c:= sqrt (42)
  
  #35 lines of code...
  
  b:= a
  a:= get hero palette (2)

  #etc.
end

Variable names should rougly describe their purpose.

Right:

script, foo, begin
  variable (hero pic, hero pal, root 42)
  hero pic:= get hero picture (1)
  root 42:= sqrt (42)
  
  #35 lines of code...
  
  hero pal:= get hero palette (2)

  #etc.
end

Note: root 42 is not a very good example of variable usage. However, the author was having a difficult time thinking of random examples. He appologizes profusely.

Indentation[edit]

One tab == 2 spaces. Remember that.

When you enter a block, tab in once. When you leave a block, tab out once.

Wrong:

script, foo, begin
variable(count,npc)
count:=10
if(1==2) then, begin
while(count) do, begin
for(npc,count,1,-1) do, begin
walk npc(npc,up,1)
end
end
end
end
end

Without indentation, you'd never know that I inserted an extra end somewhere.

Right:

script, foo, begin
  variable(count,npc)
  count:=10
  if(1==2) then, begin
    while(count) do, begin
      for(npc,count,1,-1) do, begin
        walk npc(npc,up,1)
      end
      count -= 1
    end
  end
end
#end <-- the extra end

Conclusion[edit]

Hopefully, you're one step closer to producing good, clean code!