Good conventions - Githubissues

Searching for good conventions that a few of us can use to keep consistency and readability. There is no perfect solution. However, settling on a particular convention will make things easier. Below are some ideas. Let me know what you guys think. Is one method better than another? Can edit this post appropriately based on feedback. I am new with git, and will need help with this section.

This issue is a WIP.

Coding Squirrel

Some links for consideration:

Electric Imp Squirrel Style Guide
Squirrel - Try It Online (https://tio.run/#squirrel) Note: tio runs Squirrel 2.2.5 stable, and attract uses Squirrel 3.0 stable

File Specifications

LF line endings will be used. It is supported by UNIX (Linux and Mac OS X), as well as properly viewable/editable within notepad on Windows 10 1809+ (only took 33 years!). If your editor does not support changing line endings, use endlines. I created an AUR package of endlines for Arch Linux users.

Comments

// Single line comments above referencing code
local x = null

Statements

Squirrel 3.0 Reference Manual - Statements

// Preferred single line statement
x = null

// Semi-colons can effect readability
x = null

Spaces

// A single space should separate a keyword and brackets.
local x = [ "Bar", "Eek" ]

// A single space should separate a keyword and parenthesis.
if ( x != null )
{

}

Indentations

Spaces retain presentation across screens. Tabs conserve file size and allow your code editor to handle presentation preference. We will use tabs instead of spaces.

Blocks

Blocks in squirrel are indicated by use of curly braces. The preceding curly brace may be placed on the same line (conserving file size), or the following line by itself (visually lining up with proceeding brace). The latter would match the style seen with C in this repository and should be used.

if ( x != null )
{

}

Variable Names

// Variable names should use lower camel case
local someVariable = null

// Static immutable variables should use uppercase
static STATIC_VARIABLE = "This will not change."

Tables

In squirrel 3.0, it is possible to declare tables using the JSON syntax. The advantage to using the JSON syntax is the ability for spaces to exist within keys. Usage is necessary when generating data from an external source. For consistency, the JSON syntax should be used for tables.

local x =
{
  "id": 1,
  "name": "Foo",
  "price": 123,
  "tags": [ "Bar", "Eek" ],
}

Function/Method Names

// Function names should use lower camel case
someFunction()
{

}

Access Modifiers

Squirrel does not have any mechanism to restrict access to functions or variables. However, we can use python naming conventions to help differentiate how they should be used. This is useful to give a clear indication of how to use and extend a class. I don't really see a need for private access.

Public variables and functions can be accessed anywhere within their scope.
Private variables and functions should only be accessed within their class. They are indicated by proceeding an underscore.

Full Example

Git

Git/GitHub branching standards & conventions

Instance	Branch	Description, Instructions, Notes
Stable	stable	Accepts merges from Working and Hotfixes
Working	master	Accepts merges from Features/Issues and Hotfixes
Features/Issues	topic-*	Always branch off HEAD of Working
Hotfix	hotfix-*	Always branch off Stable

mickelson / attract

Good conventions #648