GUIDELINES.md

Zig Embedded Group Coding Guidelines

Style Guide

ZEG uses the regular Zig Style Guide, but derives when it comes to function naming:

• Function in ZEG code are snake_case.
• Types are still PascalCase, but when there is an abbreviation it is kept uppercase, and uses underscores to separate it from other components in the name

const namespace_name = @import("dir_name/file_name.zig");
const TypeName = @import("dir_name/TypeName.zig");
var global_var: i32 = undefined;
const const_name = 42;
const primitive_type_alias = f32;
const string_alias = []u8;

const StructName = struct {
    field: i32,
};
const StructAlias = StructName;

fn function_name(param_name: TypeName) void {
    var function_pointer = function_name;
    function_pointer();
    function_pointer = other_function;
    function_pointer();
}
const function_alias = function_name;

fn ListTemplateFunction(comptime ChildType: type, comptime fixed_size: usize) type {
    return List(ChildType, fixed_size);
}

fn ShortList(comptime T: type, comptime n: usize) type {
    return struct {
        field_name: [n]T,
        fn methodName() void {}
    };
}

// The word XML loses its casing when used in Zig identifiers.
const xml_document =
    \\<?xml version="1.0" encoding="UTF-8"?>
    \\<document>
    \\</document>
;
const XML_Parser = struct {
    field: i32,
};

// The initials BE (Big Endian) are just another word in Zig identifier names.
fn read_u32_be() u32 {}

Rules

• When using a constructor function, always use the fitting destructor function, and do not mix them:
  • init is undone by deinit
  • create is undone by destroy
  • alloc is undone by free

Terminology

There's a lot of words out there, and sometimes precise and uniform language helps communicating.

The following table contains words we should try to use when referring to certain things or actions.

Explanation	Primary Term	Accepted Alternative	Don't use
Continuous sequence of bytes without an inherent delimiter. It doesn't matter if you write 10, then 20 bytes or 20, then 10 bytes.	Stream
A known-length sequence of bytes with well defined boundaries. Not necessarily fixed size.	Datagram	Packet
A piece of known-length data without well defined boundaries	Chunk
Data is inserted into a continous stream.	write
Data is extracted from a contious stream.	read
Data is transmitted as a single datagram.	send
Data is received as a single datagram.	receive
The action of setting the level of a GPIO pin.	set		write
The action of reading the level from a GPIO pin.	get		read
The initiator of an I²C/SPI transfer.	Host	controller	master
The receiver of an I²C/SPI transfer.	Device	target	slave
The SPI line that transmits data from host to device.	HODI		MOSI
The SPI line that transmits data from device to host.	HIDO		MISO
The SPI line that transmits the clock signal.	SCK
The SPI line that selects a device.	CS	chip select	NS,NSS
The I²C line that transmits the data signal.	SDA	serial data	data
The I²C line that transmits the clock signal.	SCK	serial clock	clock
Configuring a device/peripherial via a config structure	apply		configure
Configuring a device/peripherial via a list of arguments	configure		apply

TODO:

• init/setup/open/create