ableos/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

/// in example.hb
a := fn(): void {}

Not Allowed

/// in fat32.hb
a := fn(): void {}

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.

// 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

if x == y {\n
\tlog(z)\n
}\n

Not Allowed

if x == y {\n
\0x20\0x20\0x20\0x20log(z)\n
}\n