From 52c9c9e03bb6d4c856510fda2e4d68dac03043e1 Mon Sep 17 00:00:00 2001 From: javalsai Date: Sun, 22 Jun 2025 01:41:32 +0200 Subject: [PATCH] docs: add guide on project structure and conventions --- docs/CONTRIBUTING.md | 2 +- docs/structure.md | 89 ++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 90 insertions(+), 1 deletion(-) create mode 100644 docs/structure.md diff --git a/docs/CONTRIBUTING.md b/docs/CONTRIBUTING.md index 8186fa7..0f4ae69 100644 --- a/docs/CONTRIBUTING.md +++ b/docs/CONTRIBUTING.md @@ -12,7 +12,7 @@ For small fixes or incremental improvements simply fork the repo and follow the 1. [Fork](https://help.github.com/articles/fork-a-repo/) the repository and [clone](https://help.github.com/articles/cloning-a-repository/) your fork. -2. Start coding! +2. Start coding! (it might be helpful to read a [quide on the project structure and conventions](structure.md) before this) * Configure clangd LSP by generating `compile_commands.json` (e.g. `bear -- make` or `compiledb make`) * Implement your feature. * Check your code works as expected. diff --git a/docs/structure.md b/docs/structure.md new file mode 100644 index 0000000..32c4a3d --- /dev/null +++ b/docs/structure.md @@ -0,0 +1,89 @@ +# Introduction + +This file aims to explain the basic project structure and some code conventions +and patterns used for contributors. If you plan on contributing a considerable +amount of code, please read this thoroughly to keep the project behavior +consistent. + +Even if your changes are not very related to the code, this guide can help to +understand how they can be related to the rest of the project and what side +changes it can require. + +# Structure + +The file structure is very simple, you have `.c` files in `src/` with their +header `.h` counterpart in `include/`, they are listed in the `Makefile` and +built all together on the same layer. + +Each file contains functions aimed to provide some specialized behavior, they +tend to follow a common prefix (like `vec_` for vector functions) to avoid name +collisions with themselves. + +## Important Files + +The `main.c` of course provides the entry point of the program, then each file +has special functionality, but a special one is `util.h`, is linked with almost +every file and provides some shared utilities to dealing with UTF-8, dynamic +Vectors and other stuff. + +`log.c` is also an important file as it provides logging utilities for +debugging, there's no need to deal with it's initialization, it behaves just +like standard printing utilities but integrated into the configured logfile. + +# Debugging + +The log module can be easily used by just setting up the `LIDM_LOG` +environmental variable to the logs output path. + +# Header Files + +But what if you create a new file? It's important that the definitions are only +evaluated once by the compiler, even if they are included by several files. For +this, you can use this simple trick (assume this is for a file named +`mylib.h`): + +```h +#ifndef MYLIBH_ +#define MYLIBH_ + +// library contents +// ... + +#endif +``` + +It's also a good idea to include brief comments above functions if it's not +evident what they do and name all parameters. + +# Nullability Checks + +Nullability checks are not really enforced in the code but it's never a bad +idea to include them, however, `gcc` doesn't support them under certain +conditions. + +For this you can use `NULLABLE`, `NNULLABLE` and `UNULLABLE` macros from +`"macros.h"` to conditionally include `_Nullable`, `_Nonnull` and +`_Null-unspecified` respectively. + +# Handling & Support + +Every function should properly handle allocation failures (avoid them with +stack arrays where possible), support UTF-8 strings, use the `log` module +instead of printing to stdout (messing with the state of the ui) and free all +lost memory (if it can be lost before reaching the final stage where it execs +another program, I'm fine with not freeing memory still reachable at the end). + +# Code format, style and linting + +Be reasonable and follow `clang-format` and `clang-tidy` rules. `clang-tidy` +can be quite pedantic with the current primitive rules, so feel free to use +`LINTIGNORE` or discuss if said rule should be enforced in first place. + +Also avoid grammar typos and for shell scripts use `shellcheck`, you can run +this checks with `make pre-commit` if you have the required tools. + +# Documentation + +Please, also check if there's documentation related to the feature/changes you +are implementing, could be on markdown or manpages, if there is and you have +some spare time, it's really helpful to update it; although not enforced.