From f0e6aa38c703f5e7d1262898bdd9f97a0e80398e Mon Sep 17 00:00:00 2001 From: Quinn Date: Tue, 12 Aug 2025 11:46:26 +0200 Subject: [PATCH] seperate out general good C practice from the style guide --- docs/dev/correct-c.md | 13 +++++++++++++ docs/dev/styleref.md | 10 ++-------- 2 files changed, 15 insertions(+), 8 deletions(-) create mode 100644 docs/dev/correct-c.md diff --git a/docs/dev/correct-c.md b/docs/dev/correct-c.md new file mode 100644 index 0000000..2bf1cc2 --- /dev/null +++ b/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. diff --git a/docs/dev/styleref.md b/docs/dev/styleref.md index 17b34a7..6ffeb29 100644 --- a/docs/dev/styleref.md +++ b/docs/dev/styleref.md @@ -11,16 +11,10 @@ - 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] +- Code must be written correctly, read [Correct C](./correct-c.md) if more information is required. +- K&R style braces/[indentation](https://en.wikipedia.org/wiki/Indentation_style) - 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). - -[cstd]: this is a general C practice, included since it is something commonly done incorrectly. -[wikiindent]: