We follow a pattern on C to allow us to emulate (poorly) the modules of languages such as Ada and Modula-3.

C/C language source and header files should begin with the prefix pz_. The C language does not have a namespace concept, prefixing C symbols with pz_ can make linking, and debugging linked programs easier. In C use the pz namespace.

Sometimes a file (header or source file) will cover multiple concepts. In these cases the order above may be broken in order to keep things with the same concept together. For example, this may mean placing a struct followed by the functions that operate on it, followed by a global variable, and the functions that operate on it.

In some cases the environment may force a different order. For example C preprocessor macros may need to be placed in a specific order.

Generally items within a file should be organised as follows:

If a statement is too long, continue it on the next line indented two levels deeper (but less or more is okay depending on the situation).

Break the line after an operator:

And usually at an outer element if possible, this could be the assignment operator itself.

Sometimes line-breaking can be done nicely by naming a sub-expression, give it a meaningful name:

You may choose to align sub-expressions during breaking. This is recommended when an expression is broken over several lines. Even though name is short we give it its own line because the other expressions are long.

When things that may need wrapping occur at different depths within an expression then different levels of indentation can help convey that depth:

These two sub-expressions are aligned, but they don’t have to be (see Tables below).

Sometimes breaking early can allow you to align things towards the left and give them more room. For example we prefer:

While clang-format prefers:

Use all lowercase with underscores to separate words. For instance, soul_machine.

Use all uppercase with underscores to separate words. For instance, MAX_HEADROOM.

TODO: Maybe make function-like macros belong here.

Static data should begin with s_ for both file-local and class members.

Use first letter uppercase for each word, other letters lowercase and underscores to separate words. For instance, Directory_Entry.

If something is both a struct and a typedef, the name for the struct should be formed by appending ‘_S’ to the typedef name. This overrides the style for typedefs above:

For unions, append ‘_U’ to the typedef name.

Classes use CamelCaseWithInitialCap.

Fields of classes (but not structs) should begin with m_, static data members should begin with s_.

These behave differently (better) than C macros. They don’t need to look like C macros. Use _ to seperate words with initial capital letters. Eg: ‘My_Const_Expr’

C99 provides many basic data types, char, short, int etc. All being defined to be at least a certain size. These should be used when the size doesn’t exactly matter. For example use bool for booleans and int or unsigned when you’re counting a normal amount of something - you should not need to use the macros such as INT_MAX. When size matters the inttypes.h types are strongly recommended, including the fast types, eg: uint_fast32_t and their macros.

float should be used in preference to double which is seldom necessary and uses more memory. Don’t rely on exact IEEE-754 semantics.

Since C99 does not specify the representation of signed values, we will assume 2’s complement arithmetic (we’re not exactly C99 pure).

Endianness and alignment must not be assumed. If laying out a structure manually align each member based on its size.

Operating system APIs differ from platform to platform. Although most support standard POSIX calls such as read, write and unlink, you cannot rely on the presence of, for instance, System V shared memory. Adhere to POSIX-supported operating system calls whenever possible since they are widely supported, even by Windows.

The CFLAGS variable in the Makefile will request that modern C compilers fail to compile Plasma if it uses non-POSIX APIs.

When POSIX doesn’t provide the required functionality, ensure that the operating system specific calls are localised.

We require a C99 compiler. However many compilers often provide non-standard extensions. Ensure that any use of compiler extensions is localised and protected by #ifdefs. Don’t rely on features whose behaviour is undefined according to the C99 standard. For that matter, don’t rely on C arcana even if they are defined. For instance, setjmp/longjmp and ANSI signals often have subtle differences in behaviour between platforms.

If you write threaded code, make sure any non-reentrant code is appropriately protected via mutual exclusion. The biggest cause of non-reentrant (non-thread-safe) code is function or module-static data. Note that some C library functions may be non-reentrant. This may or may not be documented in the man pages.

In addition to sticking to C11 (which is the minimum required for "modern C"). We also forbid use of exceptions and RTTI, they’re unnecessary and add too much magic. You should also be frugal with templates and vtables. You may follow guidelines for "good C" from other sources, I’ve been reading the Essential C series and found it helpful.

If you need a feature from a newer version of one of these standards, but we don’t have the need to upgrade our minimum dependencies and the new feature is a change you can easily add as a utility function. Then add it to pz_cxx_future.h/cpp (or create a new future file for other libraries), and indicate in a comment what version of the standard they’re from.

Then when we do update our dependencies we can look in these files to easily find what workarounds we can remove.

This also applies to things that haven’t been added to a standard but might be someday.

This is one of the most important sections in the coding standard. Here we mention what other tools Plasma may depend on.

Clang-format has been configured and mostly does the right thing. But often doesn’t. You could check "what would clang-format do" but it is not to be relyed on.

Place the pointer or reference qualifier between the type and the variable name.

This avoids confusion that might occur when the pointer qualifier is attached to the type.

TODO: find out if the same trap exists for C++ references.

And makes the symbol easier to notice.

Use one statement per line.

In argument lists, put space after commas. Include parameter names in the declaration as this can aid in documentation.

Unlike other code blocks, the open-curly for a function should be placed on a new line.

If the parameter list is very long, then you may wish, particularly for long or complex parameter lists, place each parameter on a new line aligning them. Aligning names as in variable definition lists is also suggested but not required.

Variable declarations shouldn’t be flush left, however.

When defining multiple variables or structure fields or in some cases function parameters, then lining up their names is recommended. This also applies to structure and union fields.

There should be one line of vertical space between the definition list and the next statement.

Prefer enums to lists of #defines. Note that enums constants are of type int, hence if you want an enumeration of chars or shorts, then you must use lists of #defines.

If a thing will have methods that act on instances, it is a class and should begin with the "class" keyword, and keep its data members private. Otherwise it is a struct and shell begin with a struct keyword..

Bare pointers aren’t "modern C++". However in Plasma’s runtime system they show that the lifetime of the object is handled elsewhere. Either it is known to live a very long time and live in static data or on the C++ heap and destroyed when the program ends. Or it is a GC allocated object and we additionally guarantee that in the time while it’s live (passed around) it’s impossible for a GC to occur (there’s also a NoGCScope present.

TODO: Describe how we root GC pointers within runtime code.

C++ exposes implementation details of classes in their declarations as private members. This means that changes to these internal details can cause unnecessary recompilation. On the other hand it allows the compiler to inline functions defined in the class definition that do access private members.

When the latter need is not great it can be good to avoid creating the former problem by hiding these details. There are a few different techniques

The pImpl pattern is done where the class now contains a pointer to a class that contains the actual implementation. This pointer should be a std::shared_ptr and the outer class is expected to be passed by value rather than by reference. While this still allows callers to use object.method() style calls (which then forward), it breaks the normal expectations where "most objects should be passed by reference". Of course you can pass them by reference but doing so creates an extra pointer indirection. Passing by value isn’t great either, causing extra work in the std::shared_ptr to maintain its reference count.

There’s another pattern where an abstract base class contains a virtual public interface and a private derived class containing the actual implementation. We avoid this because we want to avoid vtables when we can.

Therefore the pattern we use in Plasma’s runtime (when we choose to hide implementation details at all) is to forward declare the class, and define it in an implementation file or implementation-only header file. The public interface is defined as non-member forwarding functions. This pattern can be seen in pz_gc.h and pz_gc.impl.h.

When code or data is tabular then using a tabular layout makes the most sense. This may be something formatters cannot handle, some will allow you to describe excisions.

We don’t have a good example of this in the code base, however the data in pz_builtin.c could probably be set out in a table. If it were it might look like:

TODO

Macros should either be expressions (they have a value) or statements (they do not), this must always be clear. If necessary make a single statement using a block. The do {} while (0) pattern is not necessary since bodies of if statments may not be macros without their own curly brackets.

C expressions may have side-effects, this is okay most of the time but can lead to confusion with macros. A macro can evaluate its parameters more than once. Avoid doing this in your macros, and if you must add a comment explaining that this can happen.

It’s very easy for C++ compilers to want to perform type conversions for you. This is frequently done via conversion operators and constructions that take a single argument. The later are easy to provide by mistake, therefore 1-arg constructors should be declared as explicit, which will prevent the compiler from using them automatically.

When implicit conversion is desired, add a comment to tell anyone reading your code that you didn’t forget, that you want it to be implicit.

C will create implicit copy constructors. These don’t always do the right thing so it is best to either create them explicitly or tell C you don’t want them. The same is true for copy assignment operators.