write a note

docs/dev/correct-c.md

@@ -0,0 +1,13 @@
+# Correct C
+A monster list about bad code practices for the absolute beginners.
+Things obviously should be taken with a grain of salt, just stating the obvious.
+
+- Functions without parameters will be defined with `void` in the parameter list, as opposed to leaving it empty. (e.i. `(void)` rather than `()`)
+- (public-facing) names mustn't be prefixed with `_`, this is a reserved identifier.
+- `typedef`s mustn't be suffixed with `_t`, this is a POSIX reserved identifier.
+- `typedef`s are discouraged, unless the name alias is clear in what it stores. (e.i. `u32` for a 32 bit unsigned integer)
+- Functions should do one thing, and do it well.
+- `inline` functions should serve as a replacement for macro definitions, don't put things in here that you wouldn't put in a macro. (block ≤5 lines)
+- Mark all implementations in a `*.c` file with `static` if there isn't a matching definition in a `*.h` file. (unless there's a clear reason to)
+- When a function parameter takes in a pointer, and does not modify the pointed at data, a const pointer should be used. (`const int *ptr`)
+- Try to limit yourself at ~112 columns, but generally avoid overly long lines.

docs/dev/styleref.md

@@ -10,17 +10,24 @@
 - clang-tidy
 - linux / unix-like machine
 
-### style guide
-- parameterless functions should have the `void` parameter.[^cstd]
-- symbols mustn't be prefixed with `_`; this is a C standard reserved symbol.[^cstd]
-- typedefs (or anything else for that matter) mustn't be suffixed with `_t`, this is reserved by POSIX.[^cstd]
-- functions should do one thing, and do that thing well.[^cstd]
-- K&R style braces/indentation[^wikiindent]
-- typedefs are discouraged
-- snake_case is used for all user-defined symbols. Macros are often all-uppercase, same goes for enums and other types of compile-time constants.
-- tabs are used for indentation, spaces are used for alignment.
-- British spelling is preferred, but not enforced. What is enforced is that British variants of the symbols are available.
-- commits should attempt to convey clearly what is being changed, for the sanity of the maintainer(s).
+### code information
+The project is written in the [GNU dialect](https://gcc.gnu.org/onlinedocs/gcc/C-Dialect-Options.html) of [C99](https://www.en.cppreference.com/w/c/99.html).
+Where we have dependencies on:
+| library                           | summary                                                 |
+|:----------------------------------|:--------------------------------------------------------|
+| [libarchive](libarchive.org)      | compression / decompression of various formats.         |
+| [glfw](https://www.glfw.org/)     | window creation / input handling.                       |
+| [openGL](https://www.opengl.org/) | hardware accelleration, for handling graphics.          |
 
-[cstd]: this is a general C practice, included since it is something commonly done incorrectly.
-[wikiindent]: <https://en.wikipedia.org/wiki/Indentation_style>
+It is intended to be platform-agnostic, within reason. But the main focus is for [UNIX](https://unix.org/)-based systems with [x86_64](https://en.wikipedia.org/wiki/X86-64) architecture.
+Within [intdef.h](/src/util/intdef.h) there live definitions for fixed-width integer types.
+
+### style guide
+- Code must be written correctly, read [Correct C](./correct-c.md) if more information is required.
+- `snake_casing` is used, with no [Hungarian notation](https://en.m.wikipedia.org/wiki/Hungarian_notation). (macros are all-uppercase, with a few exceptions)
+- [K&R style braces/indentation](https://en.wikipedia.org/wiki/Indentation_style) should be used.
+- For indentation tabs are used, and are assumed to be 8 spaces wide. For alignment spaces should be used.
+- A space should precede a pointer `*`. Where it is attached to the name, rather than the type. For `const` clarity, and chains such as: `u8 *a, *b, *c;`. This is true for functions as well: `void *malloc(size_t n);`
+- Generally speaking, British spelling is preferred. Define potential macros for, or when using alternate dialects.
+- Grammar should be correct. (`don't` or `do not`, not `dont`)
+- Commits should attempt to convey clearly what is being changed, for the sanity of the maintainer(s).

src/dat/nbt.c

@@ -9,6 +9,7 @@
 #include "../util/compat/endian.h"
 #include "../util/intdef.h"
 
+// WARN: does not have public-facing definition
 int nbt_primsize(u8 tag) {
 	switch (tag) {
 	case NBT_I8:  return 1;

test/dat.h

@@ -1,7 +1,7 @@
 #include <stdint.h>
 
 #include "../src/util/conf.h"
-#include "../src/util/types.h"
+#include "../src/util/intdef.h"
 #include "t_arith.h"
 #include "t_conf.h"
 #include "test.h"

test/t_arith.h

@@ -2,6 +2,7 @@
 
 #include "test.h"
 
+/* tests arithmetic shift for signed integers (rather than logical shift) */
 int test_sar(void *dat) {
 	(void)dat;
 	return assert_true(-3 >> 5 == -1);

test/t_conf.h

@@ -5,7 +5,7 @@
 #include <string.h>
 
 #include "../src/util/conf.h"
-#include "../src/util/types.h"
+#include "../src/util/intdef.h"
 #include "test.h"
 
 // Environment saver structure for conf_getpat tests