rubyx/CodeStyle.md

# Code Style and Conventions

Just  few things that have become important enough to write down. Apart from what is written here standard blah applies (ie RoboCop/Reek stuff).

## Formatting

### Line Length

While the days of 80 are over, too big steps seems difficult. I've settled on 90 (ish)

### Brackets

While ruby allows the omission of brackets even with arguments, i try to avoid that
because of readability. There may be an exception for an assignment, a single call
with a single arg.
Brackets without arguments look funny though.

### Spacing and indent

Indent at 2 Spaces (no tabs, not 4 spaces)

Space around things, like assignment, operators

### Single line versions

Ruby has single line versions for mny things, like if and while. Use them if
the code fits comfortably on the line. Eg "return true if(somthing)".

Each is used a lot in ruby, and for each/collect etc and other block passing
the convention is to use curly braces for one-liners, and do-end for multi-line.

### Method length

Methods should not be more than 10 lines long. It points to bad design if they are,
spaghetti code, lack of abstraction and delegation. This may seem extreme coming from
other languages, and i admit it took me some years to see the light, but now it's pretty
much that. Longer methods will have a very very hard time to get accepted in a pull
request.

### No of arguments

Methods taking over 4 arguments are dubious. Actually 4 is already borderline. If a
method actually needs that much info, it is most likely that a class should be
created to hold some of it.

### Class length and size

On class length i am not rigid, but too large is a definitely a thing. More than 5-6
instance variables probably means the class is doing too much and should be split.
Also a total loc of more than 200-250 or method count over 20 is not a good sign.
Especially when combined with struct classes that just hold data and have too little
functionality, this may represent problems in pull request.

### Global and class variables

Global variables is one of the few design mistakes in ruby. They just should not exist,
meaning they should not be used.

Use class variables only if you are sure you understand their scoping, specifically the
difference between class variables and class instance variables. Lean towards
class instance variables.

Since classes (and thus modules) are global, class and module methods are global.
Use sparingly with good insight, as it ties the usage to the definition and
oo benefits like inheritance are lost.

## Code style

### Module functions are global

Often one thinks so much in classes that classes get what are basically global functions.
Global functions are usually meant for a module, so module scope is fitting.

A perfect example are singleton accessors. These are often found clumsily on the classes
but the code reads much nicer when they are on the module.

### Code generators

Instead of SlotToReg.new( register, index , register) we use Risc.slot_to_reg( name , name , name).
All names are resolved to registers, or index via Type. More readable code less repetition.
As the example shows, in this case the module function name should be the instruction class name.

Singletons should hang off the module (not the class), eg Parfait.object_space

## Naming

Naming must be one of the most important and difficult things in programming.
Spend some time to find good, descriptive names.
In the days of auto-complete, short cryptic names are not acceptable any more.

When naming, remember to name what something does (or is), not how. A classic misnomer
is the ruby Hash, which tells us how it is implemented (ie by hashing), but not it's
function. In Smalltalk this was called a Dictionary, which is tells us what it's for,
to look something up (with real-world reference, double points).