ableos-idl/STYLE_GUIDE.md

# Style Guide
This style guide has two modes that a guideline may be.

`strict` means that prs will be rejected if they do not follow the guideline.

`loose` means that a pr would be accepted but should later be fixed.

## Empty Functions | loose
Empty functions are typically a sign of an unfinished program or driver.

In cases where there is a clear reason to have an empty function it will be allowed.
For example FakeAlloc is only empty functions because it is a example of an the allocator api.

### Allowed
```rust
/// in example.hb
a := fn(): void {}
```
### Not Allowed
```rust
/// in fat32.hb
a := fn(): void {}
```
## Magic Functions | loose
'Magic functions' are what I am calling small helper functions that do one or two things.
### Example
```rust
a := null
magic_a := fn(){
	a = 10
}
```
The exact policy I want to have here is a bit fuzzy. I think that functions like this are nice in certain situations and not in others.
Regardless of if you use them or not, put a comment above the function explaining rational.


## Magic Numbers | loose
The policy on magic numbers is make them const and have a comment above them. Typically linking to a source of information about the magic number.

This helps cut down on magic numbers while making acceptable names and atleast half assed documentation. 

Constants are inlined anyways, so its the same thing in the binary.

```rust
// The standard vga port is mapped at 0xB8000
$VGA_PTR := 0xB8000
```

## Tabs Vs Spaces | strict
I prefer for hblang code to use hard tabs.

The rational behind this is that a tab is `1 Indent` which some developers might want to be various different sizes when displayed

Soft tabs do not allow this user/editor specific as soft tabs always become spaces.

Bottom line is this is an accessibility feature.

There are some samples below.
```
\t means hard tab
\n means new line
\0x20 means space
```

### Allowed
```rust
if x == y {\n
\tlog(z)\n
}\n
```

### Not Allowed
```rust
if x == y {\n
\0x20\0x20\0x20\0x20log(z)\n
}\n
```