Coding Standards

Coding Standards


Table of Contents

  1. Commenting
  2. Classes
  3. Variables
  4. Aliases
  5. Strings
  6. Line Length
  7. White Space
  8. Constants
  9. Parentheses
  10. Versions

Commenting
When writing your own code, the script must begin with a header. Something that will at least explain who created it in the first place.
ex.

#+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+
# ■ Title
# ■ Author:
# ■ Version:
# ■ Date:
# ■ Site: Optional
#+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+=+

Although I usually don’t do this, all classes and methods should have a comment describing the process or what was added.   Single line comments should precede the described block of code and should be  indented at the same level. Code that is not self-documenting should be commented.

However, very short comments can appear on the same line as the described  code, but should be shifted far enough to separate them from the statements.If more than one short comment appears in a chunk of code, they should all be indented to the same tab setting. Attribute declarations should always have a trailing comment.


Classes
All classes must be named consistently with the default code, namely:

  • Data      – Any class that defines database information
  • Game      – Any class that defines specific game data for specific session
  • Sprite    – Any class that defines a specialized sprite class
  • Spriteset – Any class that defines multiple sprites
  • Window    – Any class that defines a specialized window class
  • Arrow     – Any class that defines a specialized arrow class
  • Scene     – Any class that defines a specialized scene

Variables
All variable names must be reasonably descriptive. Use of class and global variables should be limited. Any variable used by the default system can not have its use changed.


Aliases
Aliasing a method is preferable to overriding it; an alias should be used whenever possible to increase compatibility with other scripts. There are multiple ways to alias, but they all have the same result with just a slightly different functions:
alias :new_func :func
alias_method :new_func, :func
alias_method(:new_func, :func)

the difference between:
alias :new_func :func
alias_method :new_func, :func

is minimal, but there is a small bit:
alias is a keyword, and alias_method is a method call.
alias_method(:new_func, :func)
Next, the “alias” can only take “identifiers” or “symbols”
alias new_func func #identifiers
alias :new_func :func #symbols

Symbols are an object, and are used to represent identifiers internally. Also commonly used as symbolic constants–a symbol is basically an immutable string, in which only ONE instance of the object exists in memory (per value).

The “alias_method” method, exists in the module class (can only be called from within a class/module definition) and can only take “symbols” or “strings”

alias_method(:new_func, :func)
alias_method 'new_func', 'func'

note: calling a method in Ruby does NOT require you include parentheses.

Finally, alias behaves differently depending on the scope/context of the call. alias_method always acts as a call to the Class/Module objects “alias_method” method–which is another thing: alias_method can be redefined, alias cannot.
Also, alias_method cannot be called in the global scope, whereas alias can.

Otherwise, generally, there isn’t much of a difference–at class/module scope, alias/alias_method behave the same.

also (this part is just my preference) I generally use:
unless method_defined?(:new_func)
alias :new_func :func
end

However, what you SHOULD know about this, is that it is ONLY necessary (I think) for when you start alias/redefining internal (Sprite, Window, Bitmap) classes, and it is to prevent “F12 reset errors.”

The problem is (from what I can tell) when you reset an RPG Maker game with F12, it will reload all user scripts (redefining all classes) even though the interpreter retains all definitions, etc. It, however, doesn’t *seem* to redefine any of the internal classes, and when it hits the alias for an internal class the second time, it will re-alias the new method with the new method, which makes the new method reference itself.
*exhales*
Then, when your aliased method calls itself, RPG Maker cries about “Stack Level Too Deep” because the self-referential method call becomes an endless loop and RPG Maker doesn’t allow recursion anyways.

But yea, those are mostly edge cases that one might not run into, but it’s good to be aware of their existence; and mostly what I have learned from my own experience.


Strings
Strings should normally be defined with single quotes (‘example’); this decreases the processing time of the engine. Double quotes are useful when using the following features:

  • substitutions, i.e. sequences that start with a backslash character (e.g. \n for the newline character)
  • expression interpolation, i.e. #{ expression } is replaced by the value of expression

Line Length
Lines should not cause the the viewer to have to scroll sideways to view them in the script editor. When the line needs to be broken, it should follow the following guidelines, in preferential order:

  • Break after a comma. 
  • Break before an operator.
  • Prefer higher-level breaks to lower-level breaks. 
  • Align the new line with the beginning of the expression at the same level on the previous line.

If the above rules lead to confusing code or to code that’s squished up against the right margin, just indent 4 spaces instead.


White Space
A blank line(s) should be used in the following places:

  • Between sections of a source file
  • Between class and module definitions
  • Between attributes and the class definition
  • Between methods
  • Between the local variables in a method and its first statement
  • Before a block or single-line comment
  • Between logical sections inside a method to improve readability

Blank spaces should be used in the following places:

  • A keyword followed by a parenthesis, e.g. if (some_boolean_statements)
  • After commas in argument lists, e.g. def method (arg1, arg2, …)
  • All binary operators except ‘.’, e.g. a + b; c = 1

Constants
Numerical values that are used constantly and have the same purpose for being used, is encouraged to be made a constant value instead of being hard coded. Also if a numerical value has a important function that can be changed then it is also encouraged for it to be made a constant.


Parentheses
It is generally a good idea to use parentheses liberally in expressions involving mixed operators to avoid operator precedence problems. Even if the operator precedence seems clear to you, it might not be to others -— you shouldn’t assume that other programmers know precedence as well as you do.


Versions
You should document the script with the current version. Here is a general guideline to recording this.

Format : A.BC

A = Main Version or Rewrites
B = Additions or Modifications
C = Bug Fixes


Remember you can format your code anyway you want, this is just my option.
Updated on 02.16.2013

One comment on “Coding Standards

  1. Pingback: ACE Skill Shop [RMXP] « Bigace World

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out /  Change )

Google photo

You are commenting using your Google account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )

Connecting to %s