Core Topic – Animations

Contents

• Why is Using a Consistent Style Important?
• Variable Naming
  • Classes
  • Interfaces
  • Local Variables and Class Properties
  • Constants and Enums
  • Spelling
• Class Defining
• Function Defining and Calling
  • Defining Class Functions
  • Calling Class Functions
  • Function call/definition syntax
• Commenting
  • Doc Comments
• Miscellaneous
• Helpful Regexes

---

This page refers to coding and file naming styles. For interface style guidelines look at the Interfaces page.

Why is Using a Consistent Style Important?

Good question. If you ask me, these are the main reasons:

• It looks nice.
• Collaborative projects are much more hassle free when everyone uses the same style.
• Your code can be read and understood by others.

No one is going to force you to stick to all of these (although Silica enforces some of them). Some might seem a bit excessive, but that's how Silica is coded, and how we believe Silica programs should also be coded.

Variable Naming

Classes

Classes should be Pascal case; starting with an upper case letter with each other word also starting with an upper case letter.

class "MyClass"
class "ClassTwo"

Classes that extend other classes should include the extended class' name at the end of its own. For example, a class that extends Container which makes a circle should be named CircleContainer. If something extends CircleContainer that, for example, makes it flash, should be called FlashingCircleContainer.

If the class names becomes exceedingly long remove some of the words that are less relevant. This is not an overly strict rule except for the Container class. Most View subclasses do not mention View (for example, Button, Label, etc.)

Interfaces

Interfaces should follow the class naming style, but must be proceeded with an upper case 'I' (as in I for India).

interface "IMyInterface"

Local Variables and Class Properties

Local variables (including local functions) and class properties should always use camel case; starting with a lower case letter with each other word starting with an upper case letter.

local variableOne
MyClass.variableTwo

Constants and Enums

Enums and constants should be capitalised and words should be separated using underscores.

local CONSTANT_VARIABLE
MyClass.states.VALUE_ONE

Classes should define enums as a table in the properties table using the plural form of the content's name. For example, an enum used for the state of something would be defined as such:

class "MyClass" {

	states = {
		VALUE_ONE = 1;
		VALUE_TWO = 1;
	}
	
}

Spelling

British spelling must always be used (i.e., colour not color, centre not center). Aliases for class properties should also be made to allow for accessing the properties via. American spelling.

local colour = Graphics.colours.RED
MyClass.fillColour

File Naming

Classes

Classes must be have the same name as the class they define with the .lua extension and must be in the class folder. You must not define more than one class per file.

Note

The reasoning for these restrictions is to allow Silica to easily find classes when extends is called. There is a chance that the class being extended is not loaded. When this occurs Silica simply finds the file with the same name as the class being extended. Besides, it makes your code much tidier.

MyClass.lua

class "MyClass" {

}

Themes and Interfaces

Theme and interfaces should be entirely in lowercase. There are not hard set rules in place and, unlike classes, errors will not be thrown when you do not comply. However, it is convention and should be used.

Class Defining

Classes should be defined with spaces between each token. If the class extends another class, the extends call must occur immediately after the class name. Any interfaces implemented should then proceed the super class. A class cannot extend more than one class, but it can implement multiple interfaces.

The properties should then proceed the last interface. The first curly bracket should be on the same line as the class definition. Empty lines should be at the start and end of the table.

Associated properties should be grouped together, separated by an empty line. Properties should be separated with a semicolon after each item.

Empty lines should be above and below the class definition. The last and first lines of a file should be new lines.

class "MyClass" extends "SuperClass" implements "IInterfaceOne" implements "IInterfaceTwo" {

	appearancePropertyOne = false;
	appearancePropertyTwo = "Two";
	
	otherProperty = false;

}

Function Defining and Calling

Defining Class Functions

Class functions should always be defined using the class name and colon syntax. Functions must never be defined in the properties table. Class functions cannot be defined outside of the class' own file.

function MyClass:exampleFunction( argumentOne, argumentTwo )
	== program content
end

Calling Class Functions

Functions called on an instance of a class (i.e. you've called MyClass()) should use the colon syntax.

local myClass = MyClass()
myClass:exampleFunction()

Functions called on the class itself should use the dot syntax.

MyClass.staticFunction()

Function call/definition syntax

All function calls and definitions must have spaces on either side of the arguments.

function Class:hello( name, age )
	print( "Hello, " .. name .. "! You're " .. age .. " years old." )
end

Static methods should be defined with dot syntax, and use camel case starting with a lower case letter.

function Class.static()
function Class.staticFunction()

Commenting

Doc Comments

All public functions (and private if you feel like it or it's not obvious) should have comments above them in the structure below. If no return value or arguments are specified simply omit the line.

--[[
	@instance
	@desc A reasonable description of what the function does
	@param [number] arg1 == a description of what the variable is
	@param [View] arg2 == a description of what the variable is
	@param [class] arg3 == a description of what the variable is
	@return [type] returnedValue == a description of what the variable is
]]
function Class:functionName( arg1 )
	return returnedValue
end

Enum values in doc comments should be specified by the name of the table that holds it. Using ... should simply be write as such.

--[[
	@param [Animation.easings] easing == the easing function of the animation
	@param ... == the arguments
]]

File Structure

In source files, locals should be defined at the top, followed by classes, then the class' methods.

An empty line should be left at the top and bottom of files, just to make it look a bit "prettier".

local function printInfo( ... )
	print( "Info: ", ... )
end

class "MyClass" {

	name = "Object";
	
}

function MyClass:printInfo()
	printInfo( self.name )
end

``

Miscellaneous
=============

`"` should be used to define strings, not `'`

Brackets should have spaces between the brackets and it's contents. All mathematical symbols should have spaces surrounding them.

```lua
exampleFunction( argumentOne, argumentTwo )
three = ( 2 + 4 ) / 2

Helpful Regexes

These are a bunch of regexes I've found useful for fixing mistakes, feel free to use them or ad other ones.

Replace single quotes with double:

Find: '(\w+)'
Replace: "$1"

Add spaces around brackets:

Find: \(([^-\s]+)\)
Replace: ( $1 )

Replace @instance comments on :initialise functions with @constructor:

Find: (?s)(\n\n==\[\[\n\t@)instance((.+):initialise\()
Replace: $1constructor$2

Find event functions that don't return true or false

function \w+:on.*\)\n(.*(?<!return false)(?<!return true)\n)*?end

Indent list of files for use in pages:

Terminal: cd ?; find . -type f
Find: \.\/(.*?\/)(.*?\/)?(.*?\/)?(.*?\/)?(.*?\/)?(.*?\/)?(.*?\/)?(?<name>\w+)\.lua
Replace: