Code Style Guide

Introduction

This page defines code style guidelines for my projects, but you are welcome to follow them in your projects as well :)

The rules here are loosely based on both the Linux kernel coding style as well as GNU Coding Standards, with tweaks based on my personal preferences (for both my sanity and readability, some GNU rules are actually insane).

Most of these rules can be applied to all programming languages, although the main target is modern C and C++.

1. General

• Code must target either the C23 or C++23 standard (project dependent) and should compile without warnings on modern compilers (with support for at least C99/C++98). Non-standard language extensions are fully allowed (e.g. GNU C extensions).
• All files in the project directory must use UTF-8 encoding, Unix line endings, and a trailing new line.
• A single line of code cannot exceed 100 characters in length (except when breaking the line makes the code harder to read).
• Use tabs for indentation (preferred width: 8), use spaces only for alignment.
• Main development target should always be Linux.

2. Naming

• Every function, variable, constant, macro, struct, enum, filename should be written as some variant of snake case: lowercase for functions, variables, structs, enums and filenames; uppercase for constants and macros.
• Names should be descriptive, purpose can be inferred from the name alone; avoid putting the return/variable type in the name.
• Pointer and reference symbols should be placed next to the variable name, not the type.

  i32 *ptr = NULL;
  i32 *ref = &ptr;
  

3. Declaration and initialization of variables

• Declare one variable per line, this helps with both debugging and readability.
• Initialize as close to first use as possible.
• Prefer using const to #define when possible.
• Avoid variables with global scope.
• Keep the amout of local variables (e.g. in a function) below 10.
• For integer variables prefer using fixed width integers, such as int8_t, int16_t, int32_t, int64_t and their respective unsigned variants.

4. Functions

• A function should perform a single task.
• The length of a function is inversly proportional to the complexity of it. This means that a simple function which is essentially a long switch block (or many if statements) can be longer, however for non-trivial functions try to keep them under 60 lines in length (excl. braces and comments)
• Return early from a function if an error was encoutered.
• Use modern prototypes with full parameter types.
• The return type should be on the same line as the function name and its parameter list. This is a thing that the GNU Coding Standards will try to make you believe, so in short do not do this:

  i32
  fancy_function(...)
  {
  	...
  }
  

  do this instead:

  i32 fancy_function(...)
  {
  	...
  }
  

• If the parameter list is getting a little long, it can be broken into separate lines like so:

  i32 fancy_function(i32 some_int, std::vector<std::vector<std::string>> long_vector,
  		   f64 floating_point, std::vector<std::string> another_vector)
  

  Make sure the parameters are aligned, use tabs first, then spaces to refine the alignment.
• If a function is not expected to be used anywhere, and is a helper function, make it static.
• If there is something that can go wrong in a function, make it return an integer (can be applied in both C and C++), and if using C++23 (or newer), use std::expected<T, E>.

5. Includes and headers

• All #include directives should appear at the very top of the source file in this order: standard headers, external library headers, internal project headers.
  Example:

  #include <print>
  #include <vector>
  #include <string>
  
  #include <curses.h>
  #include <sqlite3.h>
  
  #include "util/typedefs.hpp"
  #include "util/file.hpp"
  

  Note the empty lines between #include directives, this is mainly to differentiate what is standard, third-party and internal.
• Headers should only expose classes, functions and data structures that might be required by other source files.
• In most of my projects I have a separate header which typedefs common integer and floating-point types (a different name in each project for whatever reason).
  Example (C++23):

  #include <cstdint>
  
  using u8  = std::uint8_t;
  using u16 = std::uint16_t;
  using u32 = std::uint32_t;
  using u64 = std::uint64_t;
  
  using i8  = std::int8_t;
  using i16 = std::int16_t;
  using i32 = std::int32_t;
  using i64 = std::int64_t;
  
  using f32 = float;
  using f64 = double;
  

  The same header in C would use typedef instead of using. Also for simplicity sake I have omitted the include guards. You can use it (and if committing to my repositories where I already use it you should), saving a couple keystrokes never hurt anyone.
• Every header must have include guards. Use either of those:

  #pragma once

  #ifndef HEADER_H
  #define HEADER_H
  ... definitions go here
  #endif // HEADER_H
  

  Or you could combine both if you feel like it:

  #pragma once
  #ifndef HEADER_H
  #define HEADER_H
  ... definitions go here
  #endif // HEADER_H
  

• If possible (and when they are finally fully supported by major compilers), make use of modules in C++ instead of #include.

6. Error handling

• Never ignore return values of functions, handle both success and error paths appropriately.
• Log errors to stderr, in C++ you would use:

  std::print(stderr, ...);

  and in C you would instead use:

  fprintf(stderr, ...)

• Exit with non-zero codes on critical errors, in places where exiting the program altogether is unexpected to the user, return a non-zero code and handle it appropriately.

7. CLI

• All programs should include the version flag (--version) as well as the help flag (both short: -h, long: --help). If any of them is encountered, the normal execution of the program should be stopped.
  Example of the --version flag output using the BSD-3-Clause license:

  [program name] [version]
  Copyright (c) [year] [creator]
  
  License: BSD-3-Clause <https://opensource.org/license/bsd-3-clause>
  This is free software: you are free to use, modify, and redistribute it under the terms of the BSD-3-Clause License.
  There is NO WARRANTY, to the extent permitted by law.
  

  Example of the -h/--help flag output:

  Usage: [executable name] [OPTIONS] [INPUT]...
  
  Arguments:
    [INPUT]...     Path(s) to the file or directory
  
  Options:
    -h, --help     Print this help text
        --version  Print version and copyright text
  
  Source code is available at: <[repository link]>
  

  Options themselves are prepended with 2 spaces, and the description is aligned to a single column. The executable name should ideally be taken from argv[0].
• If possible, provide both short and long flags/parameters.
• The CLI should be easy to use and be fully documented.

8. Formatting

• Opening and closing braces should be on their own lines, nothing else other than semi-colons and comments can be on the same line.
  There are exceptions to this rule however: when the character directly before the opening brace is the equals sign, and in the case of defining a simple array, where putting each brace on its own line would be wasting space and make the code a little more unreadable.
  Example:

  std::array<std::string> fancy_string_array = {
  	...
  };
  
  std::array<i32> simple_int_array = {1, 2, 3};
  

  In every other case it should look like this:

  if (...)
  {
  	do_stuff();
  }
  else
  {
  	do_other_stuff();
  }
  
  i32 fancy_function()
  {
  	return 0;
  }
  

  The GNU Coding Standards will try to make you believe that every single brace should be prepended by 2 spaces, supposedly to notice where the function (or conditional) body starts or ends, but this rule was written with GNU Emacs in mind (their formatter expects this). They will try to make you believe in many things, but some are downright insane and only make sense in already estabilished codebases (like GNU itself), where changing the style is not viable.
• It is acceptable to skip the braces when there is only one line in the if, else, for statement(s). Therefore this is okay:

  if (...)
  	do_stuff();
  else
  	do_other_stuff();
  
  for (i32 i = 0; i < 5; i++)
  	fancy_stuff();
  

  However when only one branch has a single line, then use braces for both:

  if (...)
  {
  	do_a_thing();
  	do_other_thing();
  }
  else
  {
  	do_single_thing();
  }
  

• Function declarations should have a leading blank line.
• Avoid putting too many blank lines.
• Keep indentation consistent with the rest of the codebase.
• In reference to the previous point, avoid deep nesting. Anything above 5 levels and you're definitely doing something wrong.

9. Comments

• Use // for short comments, as well as when closing an #ifdef/#ifndef block or a namespace (specifically when it's long, but do it every time just to be consistent).
  Example:

  #ifdef CONDITION
  	...
  #endif // CONDITION
  
  namespace file
  {
  	...
  } // namespace file
  

• Use /* ... */ for multi-line (longer) comments.
• Do not place comments that explain why a variable exists, or what a function does, it should be visible from the name and/or code.
• Document public functions (function marked with static do not need to be documented) with their brief purpose (but keep it really brief), parameter list and a return value.

10. Build and tools

• Use the included Makefile to build the project.
• Preferred compiler is clang, however since the flags are mostly compatible with gcc, you can use it as well (but remember to change it in the Makefile).
• The compiler should not emit any warnings or errors.
• Treat the compiler as your friend.

11. Version control

• Commit messages should be descriptive, avoid vague "do stuff" commit messages.
• Avoid large monolithic commits.
• Use Codeberg, sourcehut, GitLab, but not GitHub (unless you want AI to be trained on your private repositories).

12. Licensing

• The BSD-3-Clause license is preferred, but any open-source license could be used.
• Keep it open-source. It's the future.